# Duffel MCP Server

An MCP (Model Context Protocol) server that wraps the [Duffel](https://duffel.com) flights API, letting you search for flights directly from Claude Code using natural language.

## Tools Exposed

| Tool | Description |
|---|---|
| `search_flights` | Search one-way or round-trip flights by IATA code, date, cabin class |
| `get_offer_details` | Get full details on a specific offer (baggage, fare conditions, etc.) |
| `list_airports` | Look up IATA codes by city/airport name |

## Setup

### 1. Get a Duffel API Token

1. Sign up free at [duffel.com](https://duffel.com)
2. Go to **Dashboard → Developers → API tokens**
3. Create a **Test** token (starts with `duffel_test_...`)
4. Live tokens (starting with `duffel_live_...`) enable real bookings — use test for demos

### 2. Install & Build

```bash
npm install
npm run build
```

### 3. Configure Claude Code

Add to your Claude Code MCP config (`~/.claude/claude_desktop_config.json` or project-level `.claude/mcp.json`):

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

> For Claude Code CLI, use: `claude mcp add duffel node /path/to/dist/index.js`
> then set the env var in your shell or `.env`.

### 4. Restart Claude Code

Once restarted, you'll have flight search available as native tools.

## Example Prompts in Claude Code

```
Search for flights from RDU to SFO on April 15th for 2 passengers in economy

Find round-trip flights from Raleigh to London, departing May 10 returning May 20, business class

What's the cheapest flight from JFK to LAX next Friday?

Look up the airport code for Raleigh Durham

Get full details and baggage policy for offer [offer_id]
```

## Development

```bash
# Run without building (uses tsx)
DUFFEL_API_TOKEN=duffel_test_... npm run dev

# Build for production
npm run build
```

## Architecture

```
Claude Code
    │
    ▼  (MCP stdio transport)
duffel-mcp server (this repo)
    │
    ▼  (HTTPS REST)
Duffel API
    │
    ▼
Airlines / GDS
```

## Extending

Want to add booking? Add these tools next:

- `create_order` — book the selected offer
- `get_order` — retrieve booking confirmation
- `list_orders` — see all bookings

See [Duffel API docs](https://duffel.com/docs/api) for the full reference.