mcp-travelcode

What is this?

MCP TravelCode is a Model Context Protocol (MCP) server that connects AI assistants to the TravelCode corporate travel API. It lets AI agents search for flights and hotels, create and manage bookings, check real-time flight status, and access delay statistics — all via natural language conversations.

Built for the MCP ecosystem — works with Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Continue, OpenClaw, and any MCP-compatible client.

Key Features

• 🔍 Flight search — multi-city, one-way, round-trip with cabin class and passenger filters

• 🏨 Hotel search — property type, star rating, meal plans, refundability, price filters with streaming results

• 📊 Flight status — real-time tracking with delays, gates, terminals, and aircraft info

• 📈 Delay statistics — historical delay and cancellation data for flights and airports

• 📋 Order management — create, cancel, modify bookings; check cancellation conditions

• 🔐 OAuth 2.1 + PKCE — secure browser-based authentication, auto-refreshing tokens

• 🌍 Airport & airline data — search by name, city, IATA/ICAO code

• ⚡ Async polling — automatic background polling for flight search results

• 🔄 Dual transport — stdio (local) and Streamable HTTP (remote) support

Related MCP server: Travel Assistant MCP

Quick Start

There are three ways to use MCP TravelCode. Pick one:

A and C use the Streamable HTTP transport (multi-client, per-user OAuth). B uses stdio (one process per user, token in a local file).

A — Hosted server (zero install)

No install, no local token files. Point any MCP-capable client at:

https://mcp.travel-code.com/mcp

On first use the client opens a browser window, you log in to TravelCode, approve the consent screen, and you're done. Works in Claude for Web, Claude Desktop, Claude Code, Cursor, Windsurf, and any other client that supports HTTP+OAuth MCP servers.

Once connected, the assistant can search flights, find hotels, view and manage your orders, and pull delay stats — on behalf of the signed-in TravelCode user.

B — Local stdio (npx mcp-travelcode)

For desktop clients without HTTP+OAuth support, or air-gapped/offline setups. Each user runs the server as a child process on their own machine.

# Authenticate once with your TravelCode account (opens browser)
npx mcp-travelcode-auth auth

The token is saved to ~/.travelcode/tokens.json and auto-refreshes. Configure your client to spawn npx mcp-travelcode (examples below).

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "travelcode": {
      "command": "npx",
      "args": ["mcp-travelcode"]
    }
  }
}

Restart Claude Desktop — done! Ask Claude to search flights, book hotels, or check flight status.

Claude Code

claude mcp add travelcode -- npx mcp-travelcode

ChatGPT Desktop

Go to Settings → Tools → Add MCP Server, then add:

{
  "command": "npx",
  "args": ["mcp-travelcode"]
}

Gemini / Google AI Studio

Add to your MCP server configuration:

{
  "mcpServers": {
    "travelcode": {
      "command": "npx",
      "args": ["mcp-travelcode"]
    }
  }
}

GitHub Copilot (VS Code)

Add to your VS Code settings.json:

{
  "github.copilot.chat.mcpServers": {
    "travelcode": {
      "command": "npx",
      "args": ["mcp-travelcode"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "travelcode": {
      "command": "npx",
      "args": ["mcp-travelcode"]
    }
  }
}

Windsurf / Cline / Continue

Add to your MCP configuration (typically mcp_config.json or settings):

{
  "mcpServers": {
    "travelcode": {
      "command": "npx",
      "args": ["mcp-travelcode"]
    }
  }
}

Zed

Add to your Zed settings.json:

{
  "context_servers": {
    "travelcode": {
      "command": {
        "path": "npx",
        "args": ["mcp-travelcode"]
      }
    }
  }
}

JetBrains IDEs (IntelliJ, WebStorm, PyCharm)

Go to Settings → Tools → AI Assistant → MCP Servers → Add, set command to npx with args mcp-travelcode.

OpenClaw

mcp:
  servers:
    travelcode:
      command: npx
      args: ["mcp-travelcode"]

C — Self-host HTTP server

Deploy your own HTTP instance under your domain. The same flow as the hosted instance — clients connect by URL, OAuth happens in the browser, tokens come in the Authorization: Bearer header on every request — but running on your infra and (optionally) against your own OAuth Authorization Server.

For a quick local smoke test:

npm run build
PORT=3000 \
RESOURCE_URI=http://localhost:3000 \
OAUTH_ISSUER=https://travel-code.com \
TRAVELCODE_API_BASE_URL=https://api.travel-code.com/v1 \
  npm run start:http
# → http://localhost:3000/mcp

For a full production deploy (systemd + nginx + TLS + fail2ban), see DEPLOY.md. It documents the reference setup we run for mcp.travel-code.com and lists the placeholders to substitute when deploying under your own domain.

Requirements for self-hosting against your own AS:

• An OAuth 2.1 Authorization Server that exposes RFC 8414 metadata (or you proxy it from the sidecar, as we do for travel-code.com).

• Issued scopes match SCOPES_SUPPORTED in src/http-server.ts (currently flights:*, airports:read, airlines:read, hotels:search, tourist:read).

• Tokens accepted by the upstream TravelCode REST API in the Authorization: Bearer header.

Supported Clients

Works with any MCP-compatible client — including all major AI assistants, IDEs, and coding tools:

Tools (50)

✈️ Flight Search & Reference Data

📊 Flight Statistics

🏨 Hotel Search

🚨 Risk Alerts (duty-of-care)

🧳 Travelers (duty-of-care)

📋 Order Management

Example Conversations

Search Flights

You: Find me flights from New York to London on April 15, economy class, 2 passengers

AI: Uses search_airports → search_flights → returns formatted flight options with prices, durations, and stops

Book a Hotel

You: I need a 4-star hotel in Tokyo for May 1-5, 2 adults, with breakfast included

AI: Uses search_hotel_locations → search_hotels with star rating and meal plan filters → shows options

Check Flight Status

You: Is my flight AA100 on time today?

AI: Uses get_flight_status → shows real-time departure/arrival times, gate, terminal, any delays

Manage Bookings

You: Show my recent orders. Can I cancel order #12345?

AI: Uses list_orders → check_order_cancellation → shows cancellation conditions and refund estimate → cancel_order if confirmed

Flight Delay Analysis

You: How often is BA115 delayed? What are the stats?

AI: Uses get_flight_delay_stats → shows historical on-time percentage, average delays, cancellation rate

Authentication

MCP TravelCode uses OAuth 2.1 with PKCE — the modern standard for secure authentication. No API keys to manage or rotate.

# Sign in (opens browser for secure authentication)
npx mcp-travelcode-auth auth

# Check token status and expiration
npx mcp-travelcode-auth status

# Sign out and clear tokens
npx mcp-travelcode-auth logout

• Tokens are stored in ~/.travelcode/tokens.json

• Access tokens auto-refresh when expired — no manual intervention needed

• Each user authenticates with their own TravelCode account

Legacy mode: Set TRAVELCODE_API_TOKEN environment variable to use a static API token (skips OAuth).

Configuration

Development

git clone https://github.com/Travel-Code-Inc/mcp-travelcode.git
cd mcp-travelcode
npm install

npm run dev          # Run with tsx (hot reload)
npm run build        # Compile TypeScript
npm test             # Run tests
npm run inspect      # Test interactively with MCP Inspector
npm run start:http   # Start Streamable HTTP transport server

Project Structure

src/
├── index.ts          # stdio entry point
├── http-server.ts    # Streamable HTTP entry point
├── server.ts         # MCP server setup & tool registration
├── config.ts         # Environment configuration
├── auth/             # OAuth 2.1 PKCE flow & CLI
├── client/           # TravelCode API client
├── tools/            # 20 MCP tool implementations
├── formatters/       # Response formatting
└── polling/          # Async flight search polling

Tech Stack

• TypeScript — full type safety

• @modelcontextprotocol/sdk — official MCP SDK

• Zod — runtime schema validation for all tool inputs

• Express 5 — HTTP transport server

• Vitest — testing framework

Use Cases

• Corporate travel management — search and book business travel through AI assistants

• Travel agencies — integrate flight and hotel search into AI-powered agent workflows

• Trip planning — find flights, compare prices, check schedules via natural conversation

• Flight monitoring — track flight status, delays, gate changes in real-time

• Travel analytics — analyze flight delay patterns, airport performance, route statistics

• Booking automation — automate repetitive booking tasks through AI agents

• Customer support — help travelers check bookings, modify orders, handle cancellations

Related

• Model Context Protocol — the open standard for AI tool integration

• TravelCode — corporate travel management platform

• MCP Servers Directory — official MCP server registry

• Claude Desktop — AI assistant with MCP support

Contributing

Contributions welcome! Please open an issue or submit a pull request.

License

MIT © Travel Code