EMS MCP Server

An MCP (Model Context Protocol) server that provides LLM access to the EMS (Event Management System) API for flight data analytics.

Prerequisites

• Python 3.11+

• uv package manager

Installation

git clone <repo-url>
cd ems-mcp

# Create virtual environment
uv venv

# Activate virtual environment
# Windows (cmd):
.venv\Scripts\activate
# Windows (PowerShell):
.venv\Scripts\Activate.ps1
# macOS / Linux:
source .venv/bin/activate

# Install the package
uv pip install -e .

This creates an ems-mcp executable inside the virtual environment:

• Windows: .venv\Scripts\ems-mcp.exe

• macOS / Linux: .venv/bin/ems-mcp

Configuration

All MCP clients need three values to connect to your EMS server:

Claude Code (CLI)

Create a .mcp.json file in the project root:

{
  "mcpServers": {
    "ems-mcp": {
      "command": "C:\\absolute\\path\\to\\ems-mcp\\.venv\\Scripts\\ems-mcp.exe",
      "args": [],
      "env": {
        "EMS_BASE_URL": "https://your-ems-server.com",
        "EMS_USERNAME": "your-username",
        "EMS_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code reads .mcp.json automatically when you open the project directory.

Claude Desktop

Edit claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the server to the mcpServers block:

{
  "mcpServers": {
    "ems-mcp": {
      "command": "C:\\absolute\\path\\to\\ems-mcp\\.venv\\Scripts\\ems-mcp.exe",
      "args": [],
      "env": {
        "EMS_BASE_URL": "https://your-ems-server.com",
        "EMS_USERNAME": "your-username",
        "EMS_PASSWORD": "your-password"
      }
    }
  }
}

On macOS/Linux, use the Unix-style path to the executable (e.g. /home/user/ems-mcp/.venv/bin/ems-mcp).

Restart Claude Desktop after saving changes.

Gemini CLI

Create .gemini/settings.json in the project directory:

{
  "mcpServers": {
    "ems-mcp": {
      "command": "C:\\absolute\\path\\to\\ems-mcp\\.venv\\Scripts\\ems-mcp.exe",
      "args": [],
      "env": {
        "EMS_BASE_URL": "https://your-ems-server.com",
        "EMS_USERNAME": "your-username",
        "EMS_PASSWORD": "your-password"
      }
    }
  }
}

Available Tools

Discovery

• list_ems_systems -- List available EMS systems (start here)

• list_databases -- Navigate the database hierarchy

• find_fields -- Find fields by keyword (mode="search"), browse the field group tree (mode="browse"), or BFS-traverse entity-type databases (mode="deep"); returns numbered [N] references usable directly in other tools

• get_field_info -- Get field metadata and discrete value mappings

• search_analytics -- Search for time-series analytics by name (altitude, airspeed, etc.)

• get_result_id -- (Deprecated) Resolve [N] references to full opaque IDs; no longer needed in the standard workflow

Querying

• query_database -- Query flight records with filters, sorting, and aggregation

• query_flight_analytics -- Get time-series data for specific flights

Assets

• get_assets -- Get reference data: asset_type of fleets, aircraft (optionally filtered by fleet_id), airports, or flight_phases

• ping_system -- Check whether an EMS system is online

Resources

The server also exposes MCP resources for stable reference data:

• ems://workflow-guide -- Discovery-to-query workflow guide

• ems://systems -- List of available EMS systems (cached)

• ems://systems/{system_id}/fleets -- Fleet catalog for a system (cached)

• ems://systems/{system_id}/airports -- Airport reference data (cached)

• ems://databases/common-fields -- Index of databases with curated field vocabularies

• ems://databases/{database_name}/common-fields -- Curated common fields for a named database (e.g. FDW Flights)

Prompts

Reusable templates that pre-encode multi-step EMS workflows:

• analyze_flights -- Discovery -> query -> analytics for a tail number / date range

• compare_flights -- Side-by-side time-series comparison between two flight IDs

• search_flight_parameters -- Discover available fields by keyword, with entity-database support

Development

uv pip install -e ".[dev]"
pytest tests/

Troubleshooting

401 Unauthorized -- Check that EMS_USERNAME and EMS_PASSWORD are correct and that the account has API access.

Connection errors -- Verify EMS_BASE_URL does not include a /api suffix. It should be just the server URL (e.g. https://your-ems-server.com).

Server not found by MCP client -- Make sure the path to the ems-mcp executable in your config is an absolute path and that the virtual environment has been created (uv venv && uv pip install -e .).