jmzlx/mcp-openscope

MCP OpenScope

An MCP (Model Context Protocol) server for controlling the OpenScope air traffic control simulator. This enables natural language control of ATC operations through Claude and other MCP-compatible AI assistants.

Features

• Session Management: Start/stop browser sessions with the OpenScope simulator
• State Queries: Get real-time game state, aircraft information, conflicts, and scores
• Aircraft Commands: Control altitude, heading, speed, and ILS approach clearances
• Game Control: Load airports, adjust simulation speed, pause/unpause, and reset

Installation

Via uvx (Recommended)

uvx mcp-openscope

Via pip

pip install mcp-openscope

From Source

git clone https://github.com/openscope/openscope-rl.git
cd openscope-rl/standalone/mcp-openscope
uv sync

Prerequisites

OpenScope Server

The OpenScope game server must be running before using this MCP server:

# Clone and set up OpenScope
git clone https://github.com/openscope/openscope.git
cd openscope
npm install
npm run build
npm start  # Server runs at http://localhost:3003

Playwright Browser

The MCP server uses Playwright for browser automation. Install the required browser:

playwright install chromium

Configuration

Claude Desktop Configuration

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "openscope": {
      "command": "uvx",
      "args": ["mcp-openscope"],
      "env": {
        "OPENSCOPE_GAME_URL": "http://localhost:3003",
        "OPENSCOPE_HEADLESS": "true",
        "OPENSCOPE_PAGE_LOAD_TIMEOUT": "30000"
      }
    }
  }
}

Environment Variables

Usage

Once configured in Claude Desktop, you can interact with OpenScope using natural language:

Session Management

Start an OpenScope session in headless mode
Stop the OpenScope session
What's the current session status?

State Queries

What's the current game state?
Show me aircraft AAL123
Are there any conflicts?
What's the current score?

Aircraft Commands

Set AAL123 to climb to FL240
Turn DAL456 to heading 090
Set UAL789 to 250 knots
Clear SWA321 for ILS approach

Game Control

Load KJFK airport
Set timewarp to 10x speed
Pause the simulation
Reset the game

Available Tools

Session Management

• openscope_start_session - Start browser session and connect to OpenScope
• openscope_stop_session - Stop session and clean up resources
• openscope_session_status - Get current session status

State Queries

• openscope_get_game_state - Get complete game state (aircraft, conflicts, score, time)
• openscope_get_aircraft - Get detailed info for a specific aircraft by callsign
• openscope_get_conflicts - Get all current separation conflicts
• openscope_get_score - Get current game score and time

Aircraft Commands

• openscope_execute_command - Execute raw OpenScope command string
• openscope_set_altitude - Set aircraft altitude (flight levels)
• openscope_set_heading - Set aircraft heading (degrees)
• openscope_set_speed - Set aircraft speed (knots)
• openscope_clear_ils - Clear aircraft for ILS approach

Game Control

• openscope_load_airport - Load a specific airport (ICAO code)
• openscope_set_timewarp - Set simulation speed multiplier (1-2000)
• openscope_pause - Pause the simulation
• openscope_unpause - Resume the simulation
• openscope_reset - Reset game to initial state

OpenScope Command Reference

The MCP server supports all OpenScope commands. Here are some common examples:

Altitude Commands:

• AAL123 c 240 - Climb to FL240
• AAL123 d 60 - Descend to FL060

Heading Commands:

• AAL123 fh 090 - Fly heading 090
• AAL123 t l 45 - Turn left 45 degrees
• AAL123 t r 30 - Turn right 30 degrees

Speed Commands:

• AAL123 sp 250 - Speed 250 knots
• AAL123 - 20 - Reduce speed by 20 knots
• AAL123 + 30 - Increase speed by 30 knots

ILS Approach:

• AAL123 i 25L - Clear for ILS approach runway 25L

Direct to Waypoint:

• AAL123 d KEPEC - Direct to waypoint KEPEC

Game Control:

• airport KJFK - Load JFK airport
• timewarp 5 - Set 5x simulation speed
• pause - Pause simulation
• unpause - Resume simulation
• clear - Clear all aircraft

Architecture

This is a standalone package extracted from the OpenScope RL project. Key components:

• browser_utils.py - Browser automation and Playwright management (inlined from environment module)
• browser_session.py - Singleton session manager for MCP tool calls
• server.py - MCP server with tool definitions and handlers
• config.py - Configuration management with environment variable support
• constants.py - JavaScript scripts for game state extraction
• exceptions.py - Custom exception classes

The package has no dependencies on the main OpenScope RL environment module, making it fully standalone.

Development

Setup

git clone https://github.com/openscope/openscope-rl.git
cd openscope-rl/standalone/mcp-openscope
uv sync

Testing

# Start OpenScope server first
cd ../../../openscope && npm start

# In another terminal, test the MCP server
cd standalone/mcp-openscope
uv run python -m mcp_openscope

Building

uv build

Troubleshooting

OpenScope server not running

Error: Navigation failed with HTTP 503

Solution: Start the OpenScope server at http://localhost:3003:

cd ../openscope && npm start

Playwright browser not installed

Error: Executable doesn't exist

Solution: Install Chromium browser:

playwright install chromium

Port 3003 already in use

Error: listen EADDRINUSE: address already in use :::3003

Solution: Kill the process using port 3003 or change the port in environment variables.

Game not ready timeout

Warning: Game did not become ready within 60s

Solution: Check that:

1. OpenScope server is running and accessible
2. Port 3003 is not blocked by firewall
3. Browser can load the page (try non-headless mode for debugging)

Related Projects

• OpenScope - The ATC simulator
• OpenScope RL - RL framework for training ATC agents
• Model Context Protocol - MCP specification

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please see the main OpenScope RL repository for contribution guidelines.

Acknowledgments

• OpenScope Team - For the excellent open-source ATC simulator
• Anthropic - For the Model Context Protocol specification
• Playwright Team - For browser automation framework