xplane-dataref-mcp

An MCP server that gives any LLM client raw access to a running X-Plane 12: search its ~10,000 datarefs and ~3,000 commands by substring, read values, and fire commands — over X-Plane's own Web API. It exists mostly for the lookup problem: nobody knows the string sim/cockpit2/gauges/indicators/airspeed_kts_pilot before finding it, and the Web API itself only filters by exact name. For instructor-level operations ("place me on a 10 NM final") see its high-level sibling, xplane-mcp.

flowchart LR
    client["Any MCP client<br/>Claude · Cursor · GPT · local models"]
    server["xplane-dataref-mcp<br/>6 tools · cached catalogue"]
    xplane["X-Plane 12 Web API<br/>12.1.4+"]
    client -- "stdio / streamable-http" --> server
    server -- "REST" --> xplane

Tools

Byte-array (data) datarefs are decoded from base64 to text when they are text. Writing datarefs is deliberately absent — commands cover acting on the simulator with X-Plane's own semantics and bounds.

How it works

sequenceDiagram
    participant LLM as LLM client
    participant S as xplane-dataref-mcp
    participant XP as X-Plane 12

    LLM->>S: search_datarefs("airspeed pilot")
    Note over S: local substring search<br/>over the cached catalogue
    S-->>LLM: …/airspeed_kts_pilot
    LLM->>S: read_dataref(name)
    S->>XP: GET /api/v2/datarefs/{id}/value
    XP-->>S: 123.5
    S-->>LLM: 123.5 (float)
    Note over S,XP: Ids go stale when X-Plane restarts —<br/>a 404 refreshes the catalogue, one retry.

Quick start

1. X-Plane 12.1.4+, Settings → Network → Accept incoming connections (serves on port 8086).
2. claude mcp add xplane-datarefs -- uvx xplane-dataref-mcp — or open your client below.
3. Ask: "what's my airspeed?"

The server starts fine with the simulator down — the moment X-Plane comes up, the tools work, no restart needed.

uv tool install xplane-dataref-mcp      # or: pip install xplane-dataref-mcp
uvx --from git+https://github.com/Santisoutoo/xplane-dataref-mcp xplane-dataref-mcp   # from source

Use with your client

Every stdio config is the same idea — command: uvx, args: ["xplane-dataref-mcp"] — dressed in each client's file format. If X-Plane is not at the default http://127.0.0.1:8086, add XPLANE_URL via the config's env field (shown once, in the Claude Code example).

claude mcp add xplane-datarefs -- uvx xplane-dataref-mcp

{
  "mcpServers": {
    "xplane-datarefs": {
      "command": "uvx",
      "args": ["xplane-dataref-mcp"],
      "env": { "XPLANE_URL": "http://127.0.0.1:8086" }
    }
  }
}

{
  "mcpServers": {
    "xplane-datarefs": { "command": "uvx", "args": ["xplane-dataref-mcp"] }
  }
}

{
  "mcpServers": {
    "xplane-datarefs": { "command": "uvx", "args": ["xplane-dataref-mcp"] }
  }
}

{
  "servers": {
    "xplane-datarefs": { "type": "stdio", "command": "uvx", "args": ["xplane-dataref-mcp"] }
  }
}

[mcp_servers.xplane-datarefs]
command = "uvx"
args = ["xplane-dataref-mcp"]

{
  "mcpServers": {
    "xplane-datarefs": { "command": "uvx", "args": ["xplane-dataref-mcp"] }
  }
}

{
  "mcpServers": {
    "xplane-datarefs": { "command": "uvx", "args": ["xplane-dataref-mcp"] }
  }
}

HTTP for programmatic agents

Agents built in code connect over streamable HTTP instead of stdio:

xplane-dataref-mcp --transport streamable-http --host 127.0.0.1 --port 8000

The MCP endpoint is http://127.0.0.1:8000/mcp.

Security: the server has no authentication. On 127.0.0.1 the SDK's Host/Origin validation (DNS-rebinding protection) is enabled automatically; binding 0.0.0.0 disables it and hands control of your simulator to anyone who can reach the port. Trusted networks only.

from mcp import Client

async with Client("http://127.0.0.1:8000/mcp") as client:
    tools = await client.list_tools()

from agents.mcp import MCPServerStreamableHttp

xplane = MCPServerStreamableHttp(params={"url": "http://127.0.0.1:8000/mcp"})

Configuration

One variable.

X-Plane's Web API is unauthenticated, so point XPLANE_URL only at machines on networks you trust.

Development

git clone https://github.com/Santisoutoo/xplane-dataref-mcp && cd xplane-dataref-mcp
uv venv && uv pip install -e ".[dev]"

pytest                       # offline: every test runs against a canned Web API
pytest -m sim                # against a real X-Plane at XPLANE_URL
ruff check . && ruff format --check . && mypy .

The default suite fakes X-Plane at the HTTP boundary, so everything — including the streamable-http transport — is exercised without a simulator.

Licence

MIT.