Bhinneka MCP Toolkit

A FastMCP server that provides both Google Flights utilities and SearXNG web search via Model Context Protocol (MCP). Search for flights, look up airports, and perform web/news/image searches with standardized MCP tools.

Features

• Flight Search: Find flights between airports with flexible search criteria
• Airport Lookup: Search airports by code, name, or city with comprehensive database
• Price Optimization: Get cheapest flight options sorted by price
• Best Flights: Access Google's recommended flight selections
• Multiple Transports: Support for stdio (development) and HTTP (production) modes
• CLI Interface: Built-in testing and management commands

Installation

Using uvx (Recommended)

# Install and run directly with uvx
uvx bhinneka --help

Using pip

pip install bhinneka

Using Docker (For Remote Deployment)

# Build and run with Docker
docker build -t bhinneka .
docker run -p 8000:8000 bhinneka

# Or use docker-compose for easier management
docker-compose up

Quick Start with uvx

MCP Server Modes

# Default mode (stdio transport for Claude Desktop and MCP clients)
uvx bhinneka serve

# HTTP mode (for remote access)
uvx bhinneka serve --transport http --host 0.0.0.0 --port 8000

# Check server status and capabilities
uvx bhinneka status

Testing Commands

# Test flight search
uvx bhinneka test-search LAX JFK 2025-12-25

# Test airport search
uvx bhinneka test-airports "Los Angeles"

# Show version information
uvx bhinneka version

Short Command Alias

The package also provides short aliases: bn (new) and legacy gf.

# All commands work with the shorter alias
uvx bhinneka serve
# is equivalent to
uvx --from bhinneka bn serve

MCP Integration

With MCP Inspector

For development and testing with MCP Inspector:

uvx bhinneka serve

Then connect your MCP client to the stdio transport.

HTTP Server Mode

For production use or remote MCP clients:

uvx bhinneka serve --transport http --host 0.0.0.0 --port 8000

MCP clients can connect to: http://your-server:8000/mcp

With Claude Desktop

To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop settings:

{
  "mcpServers": {
    "bhinneka": {
      "command": "uvx",
      "args": [
        "bhinneka",
        "serve"
      ]
    }
  }
}

This configuration will:

• Automatically install the latest version using uvx
• Run the server with stdio transport (default for Claude Desktop)
• Make flight search tools available in Claude Desktop

After adding this configuration, restart Claude Desktop and you'll have access to all the flight search tools directly in your conversations.

Alternative Configuration with HTTP Transport

For advanced users who prefer HTTP transport for remote access:

{
  "mcpServers": {
    "bhinneka": {
      "command": "uvx",
      "args": [
        "bhinneka",
        "serve",
        "--transport",
        "http",
        "--host",
        "127.0.0.1",
        "--port",
        "8000"
      ]
    }
  }
}

Available MCP Tools

flights_search

Search for flights between two airports.

Parameters:

• origin (string): Origin airport code (e.g., "LAX")
• destination (string): Destination airport code (e.g., "JFK")
• departure_date (string): Departure date in YYYY-MM-DD format
• return_date (string, optional): Return date for round-trip flights
• seat_class (string): Seat class - "economy", "premium_economy", "business", "first"
• adults (integer): Number of adult passengers (default: 1)
• children (integer, optional): Number of child passengers
• infants (integer, optional): Number of infant passengers
• max_results (integer): Maximum results to return (default: 6)

flights_find_airports

Search for airports by code, name, or city.

Parameters:

• query (string): Search query (airport code, name, or city)
• limit (integer): Maximum results to return (default: 10)

flights_get_cheapest

Get flights sorted by price (lowest first).

Parameters: Same as search_flights

flights_get_best

Get Google's recommended "best" flights balancing price, duration, and convenience.

Parameters: Same as search_flights

get_server_status

Get server status and capabilities information.

Parameters: None

SearXNG Web Search Tools

These tools require SEARXNG_BASE_URL to be set (e.g., https://searxng-dxb.bango29.com).

• searx_web_search(query, engines?, language?, time_range?, safesearch?, max_results?) General web search. Returns a concise, readable list.
• searx_images_search(query, engines?, language?, safesearch?, max_results?) Image-focused results; includes image URLs where available.
• searx_news_search(query, engines?, language?, time_range?, max_results?) News category search with optional time range.
• searx_search_json(query, category?, engines?, language?, time_range?, safesearch?, max_results?) Returns compact JSON string for programmatic use.

Development Setup

Requirements

• Python 3.8+
• rye (recommended) or pip

Setup with rye

# Clone the repository
git clone https://github.com/tistaharahap/google-flights-mcp
cd google-flights-mcp

# Install dependencies
rye sync

# Run the MCP server
rye run python -m bhinneka.cli serve

# Run tests
rye run python -m bhinneka.cli test-search LAX JFK 2025-12-25

# Code formatting and linting
rye run ruff check
rye run ruff format

Configuration

Transport Options

• stdio: For MCP Inspector and direct client integration
• streamable-http: For remote access and production deployments

Environment Variables

The server uses standard MCP environment variables and configurations.

Google Flights tools do not require API keys as they use public data via the fast-flights library.

SearXNG tools configuration:

• SEARXNG_BASE_URL (required for searx_* tools), e.g. https://searxng-dxb.bango29.com
• SEARXNG_TIMEOUT (seconds, default: 8)
• SEARXNG_MAX_RESULTS (default: 10)
• SEARXNG_LANGUAGE (default: en)

Docker Deployment

Building and Running with Docker

# Build the Docker image
docker build -t bhinneka .

# Run the container
docker run -d \
  --name bhinneka \
  -p 8000:8000 \
  --restart unless-stopped \
  bhinneka

# Check container logs
docker logs bhinneka

# Stop the container
docker stop bhinneka

Using Docker Compose (Recommended)

The repository includes a docker-compose.yml file for easier deployment:

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

# Rebuild and restart
docker-compose up --build -d

Production Deployment with Nginx

For production deployments, use the nginx profile for reverse proxy and SSL termination:

# Start with nginx reverse proxy
docker-compose --profile production up -d

# This will start both the MCP server and nginx
# Configure SSL certificates in ./ssl/ directory
# Customize nginx.conf for your domain and SSL setup

Docker Configuration

The Docker setup includes:

• Multi-stage build for optimized image size
• Non-root user for enhanced security
• Health checks for container monitoring
• HTTP transport configured for remote access
• Port 8000 exposed for MCP client connections

Environment Variables

You can customize the deployment using environment variables:

# Custom host and port
docker run -p 9000:9000 \
  -e GOOGLE_FLIGHTS_HOST=0.0.0.0 \
  -e GOOGLE_FLIGHTS_PORT=9000 \
  bhinneka

# Or in docker-compose.yml:
environment:
  - GOOGLE_FLIGHTS_HOST=0.0.0.0
  - GOOGLE_FLIGHTS_PORT=8000

Connecting to Dockerized MCP Server

When running in Docker, the server is accessible via HTTP transport:

• Local access: http://localhost:8000/mcp
• Remote access: http://your-server-ip:8000/mcp

Configure your MCP client to connect to the HTTP endpoint instead of stdio transport.

Data Source

This server uses the fast-flights library to access Google Flights data. The library provides real-time flight information without requiring API keys.

License

[Add your license information here]