✈️ Flight MCP Server — SQLite Demo

A fully functional Model Context Protocol (MCP) demonstration server providing simulated flight search and booking capabilities.

[!WARNING] SIMULATION ONLY: All flights, inventory, and bookings in this system are purely simulated using fictional/sample data. This project DOES NOT integrate with any real airline APIs and DOES NOT book real flights.

What is the Project?

This project is a clean, modular Python application designed to teach the fundamentals of the Model Context Protocol (MCP). It acts as a local backend server that seamlessly connects to Claude Desktop, granting the AI safe, controlled access to a local SQLite database for exploring and booking demo flights.

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI models (like Claude) to securely connect to local or remote data sources, tools, and services. Instead of the LLM guessing or hallucinating data, MCP allows it to query a deterministic backend system.

Architecture

The system architecture follows a clean, layered approach:

Claude Desktop (Client)
        ↓ (stdio JSON-RPC)
Python Flight MCP Server
        ↓
Services Layer (Business Logic)
        ↓
SQLite Database (Data Store)

Technology Stack

• Language: Python 3.11+
• Package Manager: uv
• Framework: Official MCP Python SDK (mcp)
• Database: SQLite (local file)
• Client: Claude Desktop

Six Available Tools

The server exposes exactly six robust MCP tools to the AI:

1. search_flights: Find available flights by origin, destination, and date.
2. get_flight: Retrieve full details and metadata for a specific flight.
3. check_seats: Query live seat availability for a flight.
4. book_flight: Create a new simulated booking (requires user confirmation).
5. get_booking: Retrieve details of an existing booking via a PNR reference.
6. cancel_booking: Cancel a booking and restore seat inventory.

SQLite Demo Database

The system uses a local SQLite database (data/flightmcp.db) to store flight inventory and booking states. Note: The actual .db file is excluded from version control to prevent stale state issues.

To initialize the database with fresh demo data, run:

uv run python scripts/seed_database.py

Installation & Setup

Ensure you have uv installed, then sync the dependencies:

uv sync

Running the Tests

The project includes a robust pytest suite for backend verification.

uv run pytest

Running the MCP Server

To manually verify the server starts correctly (it will block and wait for stdio communication):

uv run flight-mcp

(Application logs are strictly routed to stderr to maintain clean MCP protocol output on stdout.)

Configuring Claude Desktop

To connect this MCP server to Claude Desktop, edit your Claude Desktop configuration file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS).

Claude Desktop Configuration Example:

{
  "mcpServers": {
    "flight-mcp": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "run",
        "--directory",
        "/Users/baratharjun/Desktop/medai",
        "flight-mcp"
      ],
      "cwd": "/Users/baratharjun/Desktop/medai"
    }
  }
}

Note: Adjust the absolute paths to match your local project directory and uv installation path.

Example Tool Usage

Once connected in Claude Desktop, you can interact naturally:

User: "Find me a flight from Chennai to Delhi on 2026-09-05." Claude calls search_flights and reads the SQLite database.

User: "How many seats are left on flight 1?" Claude calls check_seats.

User: "I want to book flight 1. My name is Test User, email is test@example.com, phone 9999999999." Claude summarizes the request and explicitly asks for confirmation.

User: "Confirmed." Claude calls book_flight and returns the fictional booking reference (e.g., FLM-XXXXXX).