Tripsy CLI

tripsy is a command-line client for the public Tripsy API at https://api.tripsy.app. The project also ships tripsy-mcp, a Model Context Protocol server that exposes typed Tripsy tools for agents and MCP-capable apps.

API documentation is available at docs.api.tripsy.app.

What You Get

• Human-readable terminal output by default.
• JSON envelopes when output is piped or --json is passed.
• Raw JSON data with --quiet.
• Breadcrumbs that suggest useful next commands.
• A command catalog for humans and agents through tripsy commands --json.
• Secure token storage using the OS credential store when available, with explicit file fallback for automation.
• A local or hosted MCP server for structured agent workflows.

Agent-specific itinerary guidance does not belong in this README. Keep it in AGENTS.md for repo-level agent instructions and skills/tripsy/SKILL.md for installable Codex skill guidance.

Install

Install the latest GitHub release:

curl -fsSL https://tripsy.app/install_cli | bash

The installer downloads the latest release, verifies checksums, installs tripsy and tripsy-mcp into ~/.local/bin, and adds that directory to your shell PATH when needed.

Install with Go:

go install github.com/tripsyapp/cli/cmd/tripsy@latest
go install github.com/tripsyapp/cli/cmd/tripsy-mcp@latest

Install a specific release:

curl -fsSL https://tripsy.app/install_cli | TRIPSY_VERSION=1.2.3 bash

Install into a custom directory:

curl -fsSL https://tripsy.app/install_cli | TRIPSY_BIN_DIR=/usr/local/bin bash

Build from a checkout:

make build
bin/tripsy --help
bin/tripsy-mcp --version

Authenticate

Login with Tripsy credentials:

tripsy auth login --username you@example.com

Interactive password prompts hide typed input on terminals. Tokens are stored in the OS credential store when available. On macOS, Tripsy uses Keychain by default.

For automation, pass a token through TRIPSY_TOKEN or store one explicitly:

tripsy auth token set YOUR_TOKEN

Non-secret CLI config is stored at:

~/.config/tripsy-cli/credentials.json

Environment overrides:

TRIPSY_TOKEN=...
TRIPSY_API_BASE=https://api.tripsy.app
TRIPSY_CONFIG_DIR=/custom/config/dir
TRIPSY_AUTH_BACKEND=auto|keychain|file

Use TRIPSY_AUTH_BACKEND=file only when you need file token storage for headless automation or compatibility.

CLI Tools

Run tripsy commands for the current command catalog, or tripsy commands --json for agent-readable metadata.

Common examples:

tripsy me show
tripsy trips list
tripsy trips following
tripsy trips create --name Italy --starts-at 2026-06-01 --ends-at 2026-06-15 --timezone Europe/Rome --cover-image-url "https://images.unsplash.com/photo-1529260830199-42c24126f198?ixlib=rb-4.1.0"
tripsy activities list --trip 42
tripsy activities create --trip 42 --name "Colosseum Tour" --activity-type tour --starts-at 2026-06-03T09:00:00Z --ends-at 2026-06-03T11:00:00Z --timezone Europe/Rome --address "Piazza del Colosseo, 1, 00184 Rome, Italy" --latitude 41.8902 --longitude 12.4922
tripsy hostings create --trip 42 --name "Hotel Eden" --starts-at 2026-06-01T14:00:00Z --ends-at 2026-06-05T11:00:00Z --timezone Europe/Rome
tripsy transportations create --trip 42 --name "Flight to Rome" --transportation-type airplane --departure-description JFK --arrival-description FCO
tripsy expenses create --trip 42 --title Dinner --price 78.5 --currency EUR --date 2026-06-03T20:00:00Z
tripsy categories create --name "Golf Clubs" --slug golf-clubs --icon-name golf --color AABBCC
tripsy documents upload boarding-pass.pdf --trip 42 --parent transportation:303
tripsy request GET /v1/me --json
tripsy doctor --verbose

Most trip subresource commands require --trip <trip-id> because the public API scopes those resources under a trip.

Output

When output is piped, or when --json is passed, commands emit an envelope:

{
  "ok": true,
  "data": {},
  "summary": "Current user",
  "breadcrumbs": [
    {
      "action": "show",
      "cmd": "tripsy trips show <id>"
    }
  ]
}

Use --quiet to print raw JSON data only.

MCP Server

Use Tripsy's MCP server when an agent or app supports MCP. Prefer MCP for model-driven workflows because tools expose names, descriptions, schemas, structured results, and safety annotations.

Hosted Endpoint

Tripsy operates a public MCP server at https://mcp.tripsy.app. OAuth-capable clients such as Claude and ChatGPT can connect directly without installing anything. Authentication uses the Tripsy OAuth authorization flow at https://my.tripsy.app.

Opening the hosted endpoint in a web browser redirects to the Tripsy AI Tools setup guide. Machine requests continue to receive the MCP OAuth challenge.

The previous https://mcp.tripsy.app/mcp endpoint remains available for existing clients.

Self-Hosted Stdio

Run tripsy-mcp locally when you want full control or stdio transport. It uses the same Tripsy token, config directory, API base URL, and secure token storage as the CLI.

tripsy-mcp

Example MCP client configuration:

{
  "mcpServers": {
    "tripsy": {
      "command": "tripsy-mcp"
    }
  }
}

Self-Hosted HTTP

Run a local streamable HTTP server:

tripsy-mcp --transport http --http-addr 127.0.0.1:8787 --http-path /mcp

The default HTTP endpoint path is /mcp, so this is equivalent:

tripsy-mcp --transport http --http-addr 127.0.0.1:8787

To host a remote MCP endpoint, run the HTTP server behind TLS:

tripsy-mcp --transport http --http-addr 127.0.0.1:8787 --http-path /mcp --disable-raw-request

Then proxy public paths to the local MCP server:

https://mcp.tripsy.app/ -> http://127.0.0.1:8787/
https://mcp.tripsy.app/mcp -> http://127.0.0.1:8787/mcp

HTTP MCP always requires each request to include Authorization: Bearer <token>. When hosted OAuth is configured, the server first validates OAuth access tokens through the issuer's userinfo endpoint, then falls back to validating Tripsy API tokens against /v1/me. It uses the validated token only for that downstream Tripsy API request, so each remote client acts as its own Tripsy user.

HTTP mode intentionally ignores --token, TRIPSY_TOKEN, keychain tokens, and legacy credentials.json tokens to avoid server-side credential fallback. For public hosted servers, keep --disable-raw-request enabled unless you intentionally want to expose the broader tripsy_raw_request tool.

For OAuth-capable remote clients, configure the public MCP URL and Tripsy OAuth issuer:

TRIPSY_MCP_PUBLIC_URL=https://mcp.tripsy.app
TRIPSY_OAUTH_ISSUER=https://my.tripsy.app
TRIPSY_OAUTH_SCOPES="profile email"
TRIPSY_API_BASE=https://api.tripsy.app

With those values, unauthenticated requests to / and /mcp include a WWW-Authenticate challenge pointing at https://mcp.tripsy.app/.well-known/oauth-protected-resource. That metadata advertises https://my.tripsy.app as the OAuth authorization server and validates OAuth bearer access tokens through https://my.tripsy.app/oauth/userinfo.

MCP Tools

The MCP server exposes the tools below. All tools are closed-world: they only interact with the Tripsy API for the authenticated Tripsy account, not arbitrary external services or URLs.

MCP Tool Conventions