# Flight Booking MCP Server

A simple MCP (Model Context Protocol) server that lets an AI assistant
like Claude search for flights, book them, check booking status, and
cancel bookings — using mock flight data, so it runs with zero API
keys or signups.

## What is this?

[MCP](https://modelcontextprotocol.io) is a standard that lets AI
models call external tools. This project exposes 4 tools an AI
assistant can call directly in conversation:

| Tool                 | What it does                                        |
| -------------------- | --------------------------------------------------- |
| `search_flights`     | Search flights between two airports on a given date |
| `book_flight`        | Book a specific flight for a passenger              |
| `get_booking_status` | Look up an existing booking by its ID               |
| `cancel_booking`     | Cancel an existing booking                          |

Flight data is generated by `mock_data.py` — deterministic fake flights
(same query always returns the same results), so you can build and
test without a real flight API. A real-API version (`amadeus_client.py`)
is included as a reference but is disabled by default — see the note
near the bottom.

## Prerequisites

- **Python 3.10+**
- **[uv](https://docs.astral.sh/uv/getting-started/installation/)** —
  used to manage dependencies and the virtual environment
- **Node.js** (only needed if you want to test with MCP Inspector, step 3 below)
- An MCP-compatible client, e.g. **Claude Desktop**

## Setup

1. **Clone the repo**

   ```bash
   git clone https://github.com/YOUR-USERNAME/flight-booking-mcp.git
   cd flight-booking-mcp
   ```

2. **Install dependencies**

   ```bash
   uv sync
   ```

   This creates a `.venv` and installs everything listed in `pyproject.toml`.

3. **(Optional) Test it standalone first**

   ```bash
   uv run python -c "import main; print(main.search_flights('BLR','DEL','2026-08-15'))"
   ```

   You should see a list of 3 fake flight offers printed as JSON — this
   confirms the code itself works, before wiring up any MCP client.

4. **(Optional) Test it as a real MCP server with the Inspector**
   ```bash
   npx @modelcontextprotocol/inspector uv run main.py
   ```
   This opens a browser UI where you can call each tool manually and
   see the JSON response — the fastest way to confirm everything works
   before connecting a real client.

## Connect it to Claude Desktop

Open your Claude Desktop config file:

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

Add this entry, replacing the path with the absolute path to where you cloned the repo:

```json
{
  "mcpServers": {
    "flight-booking": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/flight-booking-mcp",
        "run",
        "main.py"
      ]
    }
  }
}
```

Restart Claude Desktop completely (quit fully, don't just close the
window). You should see "flight-booking" listed as a connected tool.

## Try it

Ask your AI assistant things like:

```
Search flights from BLR to DEL on 2026-08-15
```

```
Book the IndiGo flight (IN855-2) for passenger Jane Doe, email jane@example.com
```

```
What's the status of booking BK1000?
```

```
Cancel booking BK1000
```

## Project structure

```
flight-booking-mcp/
├── main.py             # the MCP server — defines the 4 tools
├── mock_data.py         # fake flight data generator + in-memory bookings (default backend)
├── amadeus_client.py    # real flight API backend (Amadeus) — disabled by default, see note below
├── pyproject.toml       # project + dependency config (used by uv)
├── uv.lock              # exact locked dependency versions
├── .env.example         # template for real-API credentials
├── .gitignore
└── README.md
```

**How the mock/real switch works:** `main.py` picks a backend based on
the `USE_REAL_API` environment variable (defaults to `false`). Every
tool calls a generic `flight_backend.search_flights(...)` etc., rather
than naming `mock_data` directly — so swapping data sources never
requires touching the tool definitions themselves.

## Note on real flight data

`amadeus_client.py` shows how to wire this up to Amadeus's real
sandbox API (OAuth2 token handling, normalizing their nested JSON into
the same shape `mock_data.py` returns). However, Amadeus's Self-Service
developer portal was decommissioned in July 2026, so new signups
currently aren't possible. The file is kept as a reference pattern for
integrating any real flight API later — the mock backend is fully
sufficient for using and understanding this project as-is.