# msfs2024-mcp

> ✈️ **Also in this repo:**
> - a dark-mode PyQt6 [electronic flight checklist app](src/checklist_app/README.md) (Cessna 172S + Piper Archer II, normal/abnormal/emergency procedures) designed to float on top of MSFS 2024 — `pip install -e ".[checklist]"`, run `msfs-checklist`.
> - a Claude-powered [controls setup advisor](src/controls_app/README.md) for the Honeycomb Alpha/Bravo and VelocityOne Rudder: per-aircraft binding plans with procedure coaching, plus LLM review of your exact hardware — `pip install -e ".[controls]"`, run `msfs-controls`.

A [Model Context Protocol](https://modelcontextprotocol.io) server for **Microsoft Flight Simulator 2024**. It lets an MCP client (Claude Desktop, Claude Code, etc.) read live sim state and drive the aircraft across three capability layers:

| Layer | Source | Covers | Setup |
| ----- | ------ | ------ | ----- |
| **1. SimConnect** | Official Microsoft API (`python-SimConnect`) | Thousands of SimVars, Events (controls), bundled aircraft state | MSFS running |
| **2. FSUIPC7** | Offset table (`fsuipc` module) | Values SimConnect doesn't cleanly expose; stable offsets | FSUIPC7 installed + running |
| **3. Raw memory** | `pymem` / ReadProcessMemory | Escape hatch for anything else | Opt-in, admin rights |

> **Reality check:** SimConnect, FSUIPC, and raw memory are **Windows-only** and require a *running* MSFS on the same machine (or LAN via `SimConnect.cfg`). Run this server on that Windows host. Every layer **degrades gracefully** — if a layer isn't available, its tools return a structured `{ "ok": false, "error": ... }` explaining why, instead of crashing the server. So the server boots and the catalog/discovery tools work even before MSFS is up.

## Install (on the Windows host with MSFS)

```powershell
git clone <your-repo-url> msfs2024-mcp
cd msfs2024-mcp
python -m venv .venv
.venv\Scripts\activate
pip install -e .                 # server core (SimConnect layer)
pip install -e ".[transports]"   # optional: adds the FSUIPC7 + raw-memory layers
copy .env.example .env   # then edit if you like
```

Layer prerequisites:
- **SimConnect** — installed automatically with the `SimConnect` pip package, which ships its own `SimConnect.dll`. Just have MSFS running and loaded into a flight.
- **FSUIPC7** — install the `transports` extra (above), then download and run [FSUIPC7](http://www.fsuipc.com/) (free for basic offset access). Leave it running alongside MSFS. Both `fsuipc` and `pymem` are optional and degrade gracefully when absent, so the core server and the GUI apps run without them.
- **Raw memory** — install the `transports` extra, set `MSFS_ENABLE_MEMORY=true` in `.env`, and run the server **as Administrator**. Off by default.

## Verify it works

```powershell
python scripts\smoke_test.py
```

With MSFS loaded into a flight you'll see a live aircraft-state snapshot and an event round-trip (nav lights toggle). Off-Windows or with the sim closed, it prints layer health and exits cleanly — which is how you know the graceful-degradation path is intact.

Platform-independent tests (catalog integrity + degradation) run anywhere:

```bash
pip install -e ".[dev]"
pytest -q
```

## Wire into an MCP client

**Claude Desktop / Claude Code** — add to your MCP config (`claude_desktop_config.json` or `.mcp.json`):

```json
{
  "mcpServers": {
    "msfs2024": {
      "command": "python",
      "args": ["-m", "msfs_mcp.server"],
      "cwd": "C:\\path\\to\\msfs2024-mcp",
      "env": { "MSFS_ENABLE_FSUIPC": "true", "MSFS_ENABLE_MEMORY": "false" }
    }
  }
}
```

(If you `pip install -e .`, you can use the `msfs-mcp` console script instead of `python -m msfs_mcp.server`.)

### HTTP mode & auto-start from the companion apps

The server also runs as a shared HTTP (streamable-http) service:

```powershell
msfs-mcp --transport http --port 8787    # or MSFS_MCP_TRANSPORT=http
```

Launching **either companion app** (`msfs-checklist` / `msfs-controls`)
automatically checks `127.0.0.1:8787` and starts this HTTP instance if it
isn't already running — detached, so it keeps serving after the app closes.
Server output goes to `~/.msfs_companion/mcp-server.log`; set
`MSFS_COMPANION_AUTOSTART=0` to opt out, `MSFS_MCP_PORT` to move the port.
MCP clients that support HTTP servers (e.g. Claude Code) can then attach at
`http://127.0.0.1:8787/mcp`:

```bash
claude mcp add --transport http msfs2024 http://127.0.0.1:8787/mcp
```

Stdio remains the default transport, so the Claude Desktop config above is unchanged.

## Tool surface (23 tools)

**Connection** — `connection_status`, `connect_sim`

**SimConnect / SimVars** — `get_simvar`, `get_simvars`, `set_simvar`, `get_aircraft_state`

**SimConnect / Events & autopilot** — `trigger_event`, `autopilot_set_heading`, `autopilot_set_altitude`, `autopilot_set_vertical_speed`, `autopilot_toggle_master`

**Discovery** — `list_simvars`, `list_events` (searchable by keyword/category)

**FSUIPC** — `fsuipc_status`, `fsuipc_read_offset`, `fsuipc_read_known`, `fsuipc_write_offset`

**Raw memory** — `memory_status`, `memory_attach`, `memory_module_base`, `memory_read`, `memory_read_pointer_chain`, `memory_write`

**Resources** — `msfs://telemetry/state`, `msfs://catalog/simvars`, `msfs://catalog/events`

**Prompts** — `preflight_briefing`, `fly_to_heading_altitude`

### Examples (natural language to the MCP client)

- "What's my current altitude and heading?" → `get_aircraft_state`
- "Find me every autopilot-related variable." → `list_simvars(category="autopilot")`
- "Raise the landing gear and set flaps to the first notch." → `trigger_event('GEAR_UP')`, `trigger_event('FLAPS_INCR')`
- "Engage the autopilot for heading 270 at 8000 feet." → `autopilot_toggle_master`, `autopilot_set_heading(270)`, `autopilot_set_altitude(8000)`
- "Read FSUIPC offset 0x0560 as a long." → `fsuipc_read_offset('0x0560', 'l')`

## Safety notes

- **Writes are real.** `set_simvar`, `trigger_event`, and `fsuipc_write_offset` change the running sim. Fine for your own local flight; think before scripting them.
- **Raw memory is double-gated.** It requires both `MSFS_ENABLE_MEMORY=true` *and* `allow_write=true` per write call, because bad writes can crash MSFS. Pointer chains break on most sim updates — keep them version-pinned.
- **Reads are harmless.** All read paths are observation-only.

## Extending the catalog

`src/msfs_mcp/catalog.py` is a curated subset, not the full SDK. The generic `get_simvar` / `set_simvar` / `trigger_event` tools reach **any** SimVar or Event by exact SDK name — add entries to the catalog only to make them discoverable. Full reference: the [MSFS SDK SimVars](https://docs.flightsimulator.com/html/Programming_Tools/SimVars/Simulation_Variables.htm) and [Event IDs](https://docs.flightsimulator.com/html/Programming_Tools/Event_IDs/Event_IDs.htm) docs.

## Architecture

```
MCP client  ──stdio──▶  msfs_mcp.server (FastMCP, 23 tools)
                              │
              ┌───────────────┼────────────────┐
              ▼               ▼                 ▼
     SimConnectClient   FsuipcClient      MemoryClient
     (SimConnect.dll)   (FSUIPC7)         (pymem)
              │               │                 │
              └──────── Microsoft Flight Simulator 2024 ────────┘
```

Each client is a singleton with lazy connect, a thread lock around the native handle, and a uniform `LayerUnavailable` error contract that the server renders as structured JSON.

## License

MIT

## Companion apps

- **[EFB Checklist](checklist/)** — PyQt6 always-on-top electronic checklist (normal + emergency procedures, V-speeds) for flying alongside MSFS 2024. Ships with the Cessna 172S and Piper PA-28-181 Archer.