Duffel MCP Server

A Model Context Protocol server that gives an AI assistant a typed tool layer over the Duffel travel API — flights, stays and hire cars, searched against live inventory rather than generated from the model's own imagination.

Built in TypeScript on the official Anthropic MCP SDK. Runs over stdio, so it plugs directly into Claude Desktop or any MCP-compatible client.

Search only, by design. This server exposes no booking, payment or personal-data surface. It reads availability and pricing; it cannot spend money or make a reservation.

---

Why this exists

Travel is a good test case for agentic AI: the questions are natural language ("a week in Lisbon in May, under £800"), but the answers have to come from real inventory with real prices. A language model cannot invent a flight schedule. It needs tools.

This server provides four of them, shaped so that a model can chain them without guessing.

The tools

Tool	What it does
resolve_place	Resolves a city or airport name to IATA code(s) and latitude/longitude. Called first — flights need the IATA code, stays and cars need coordinates.
search_flights	Searches flight offers. Omit return_date for one-way. Returns cheapest offers with price, airline, departure/arrival times and stop count.
search_stays	Searches accommodation around a coordinate. Returns cheapest stays with name, rating and total price for the date range.
search_cars	Searches hire cars around a pickup coordinate. Returns rates with vehicle, supplier and total price.

The design point is resolve_place: without it, a model has to guess that Lisbon is LIS and invent coordinates. With it, every downstream call is grounded in a real identifier.

Design decisions worth noting

• Credential guard on startup. If DUFFEL_API_KEY is unset the process logs to stderr and exits non-zero, rather than starting up and failing confusingly on the first tool call.
• stdout is reserved for the MCP protocol. All logging goes to stderr. Writing anything else to stdout corrupts the JSON-RPC stream — a subtle failure mode worth designing against explicitly.
• Test tokens enforced in the smoke test. test/smoke.ts refuses to run unless the token starts with duffel_test_, so a live token can't be used by accident. It never prints the token.
• No booking surface. Booking and payment endpoints are deliberately not exposed. An agent using this server can research a trip; it cannot commit you to one.

Requirements

• Node.js 18+
• A Duffel test token — free from app.duffel.com → Developers → Access tokens

Setup

npm install
cp .env.example .env   # then add your Duffel test token
npm run build

Running

npm run dev     # development, via tsx
npm start       # production, from dist/

Using it with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "duffel-travel": {
      "command": "node",
      "args": ["/absolute/path/to/duffel-mcp/dist/index.js"],
      "env": { "DUFFEL_API_KEY": "duffel_test_your_token_here" }
    }
  }
}

Restart Claude Desktop and the four tools appear. Try: "Find me flights from Edinburgh to Lisbon in May, and somewhere to stay near the centre."

Testing

npx tsx --env-file=.env test/smoke.ts

Calls resolve_place and search_flights against the live Duffel test API. Exits non-zero on failure and never prints your token.

Architecture

src/
├── index.ts    entry point — credential guard, stdio transport
├── server.ts   MCP server: registers the four tools with zod schemas
└── duffel.ts   Duffel API client and response normalisation

Responses are normalised before they reach the model — the raw Duffel payloads are large, and an agent reasons better over a trimmed, predictable shape than over a deeply nested API response.

Tech

TypeScript · @modelcontextprotocol/sdk · @duffel/api · zod

Provenance

Built in 2026 by Ahmed Ali Qadir as the tool layer for Tourista, an AI travel product by Orbixio Ltd (UK, company no. 16587877). Extracted here as a standalone, reusable MCP server.

Not affiliated with or endorsed by Duffel or Anthropic.

Licence

MIT — see LICENSE.