faizulkhan56/local-mcp-server

Flight Search MCP Server

A Model Context Protocol (MCP) server that provides flight search and airport information functionality. This server can be integrated with MCP-compatible clients like Windsurf/Cascade to provide flight data through natural language queries.

Features

• Airport Information: Get detailed information about airports using IATA codes
• Flight Search: Search for flights between airports
• Cheapest Route: Find the cheapest flight option between two destinations
• Data Resources: Access to structured airport and flight data

Project Structure

local-mcp-server/
├── server.py              # Main MCP server (FastMCP package)
├── server_mcp.py          # Alternative server (official MCP SDK)
├── data/
│   ├── airports.json      # Airport data
│   └── flights.json       # Flight data
└── .venv/                 # Python virtual environment

Setup

1. Prerequisites

• Python 3.8 or higher
• Virtual environment (recommended)

2. Installation

1. Clone or navigate to the project directory:

   cd c:\faizul-personal\local-mcp-server
   

2. Create and activate virtual environment:

   python -m venv .venv
   .venv\Scripts\activate  # Windows
   

3. Install dependencies:

   pip install fastmcp
   # OR for the official SDK version:
   pip install mcp
   

3. Data Configuration

The server loads data from JSON files in the data/ directory:

• data/airports.json: Airport information with IATA codes
• data/flights.json: Flight routes with pricing

If these files don't exist, the server will use built-in default data.

Available Tools

1. airport_info(code: str)

Get information about an airport using its IATA code.

Example:

Input: "DHK"
Output: {
  "name": "BGD DHK",
  "city": "Dhaka", 
  "country": "Bangladesh",
  "iata": "DHK",
  "timezone": "Asia/Dhaka"
}

2. search_flights(origin: str, destination: str)

Find all flights between two airports.

Example:

Input: origin="DHK", destination="KTM"
Output: [
  {
    "number": "FB101",
    "origin": "DHK",
    "destination": "KTM", 
    "price": 120,
    "currency": "USD"
  }
]

3. cheapest_route(origin: str, destination: str)

Find the cheapest flight between two airports.

Example:

Input: origin="DAC", destination="KTM"  
Output: {
  "number": "FB102",
  "origin": "DAC",
  "destination": "KTM",
  "price": 115,
  "currency": "USD"
}

Available Resources

• file://airports: Simplified airport data (name and city only)
• flight://airports: Complete airport information
• flight://routes: All flight data

Windsurf/Cascade Configuration

MCP Client Configuration

To use this server with Windsurf, add the following configuration to your MCP config file:

Location: C:\Users\[username]\.codeium\windsurf\mcp_config.json

{
  "mcpServers": {
    "flight-server": {
      "command": "C:\\faizul-personal\\local-mcp-server\\.venv\\Scripts\\python.exe",
      "args": ["C:\\faizul-personal\\local-mcp-server\\server.py"]
    }
  }
}

Alternative Configuration (Official SDK)

If you prefer to use the official MCP SDK version (server_mcp.py):

{
  "mcpServers": {
    "flight-server": {
      "command": "C:\\faizul-personal\\local-mcp-server\\.venv\\Scripts\\python.exe",
      "args": ["C:\\faizul-personal\\local-mcp-server\\server_mcp.py"]
    }
  }
}

Usage Examples

Once configured with Windsurf, you can use natural language queries:

• "Give me airport info for DHK"
• "Find flights from DHK to KTM"
• "What's the cheapest route from DAC to DEL?"
• "Show me information about Tribhuvan International Airport"

Sample Data

Airports

• DHK: Dhaka, Bangladesh
• DAC: Hazrat Shahjalal International Airport, Dhaka, Bangladesh
• KTM: Tribhuvan International Airport, Kathmandu, Nepal
• DEL: Indira Gandhi International Airport, Delhi, India
• SIN: Singapore Changi Airport, Singapore

Sample Flights

• FB101: DHK → KTM ($120)
• FB102: DAC → KTM ($115)
• FB201: DAC → DEL ($90)
• FB202: DEL → DAC ($95)
• FB301: SIN → DEL ($210)

Development

Running the Server Standalone

# Activate virtual environment
.venv\Scripts\activate

# Run the server
python server.py

The server runs on STDIO transport, making it compatible with MCP clients.

Adding New Data

1. Add airports to data/airports.json:

   {
     "CODE": {
       "name": "Airport Name",
       "city": "City Name", 
       "country": "Country",
       "iata": "CODE",
       "timezone": "Timezone"
     }
   }
   

2. Add flights to data/flights.json:

   {
     "number": "FLIGHT_NUMBER",
     "origin": "ORIGIN_CODE",
     "destination": "DEST_CODE",
     "price": 100,
     "currency": "USD"
   }
   

Troubleshooting

Common Issues

1. Server not starting: Ensure Python path and virtual environment are correct in mcp_config.json
2. No data returned: Check that data/ directory exists and contains valid JSON files
3. Permission errors: Ensure the virtual environment and Python executable have proper permissions

Debugging

The server includes error handling and will fall back to default data if JSON files are missing or corrupted.

License

This project is for educational and demonstration purposes.

Contributing

Feel free to extend the server with additional airports, flights, or new MCP tools and resources.