# Duffel MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server that gives an AI assistant a
**typed tool layer over the [Duffel](https://duffel.com) 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](https://app.duffel.com) → Developers → Access tokens

## Setup

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

## Running

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

### Using it with Claude Desktop

Add to your `claude_desktop_config.json`:

```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

```bash
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](https://ahmedaliqadir.github.io) as the tool layer for Tourista,
an AI travel product by [Orbixio Ltd](https://github.com/AhmedAliQadir) (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](LICENSE).