SimConnect MCP docs

MCP Tools — Docs Mode

All 15 MCP tools listed here are available when the server runs with MCP_MODE=docs (and also with MCP_MODE=both). Twelve of them provide read-only access to the scraped SimConnect SDK documentation corpus: simulation variables, client events, API functions, data structures, and exception/error codes. The other three serve the guides of the github.com/mrlm-net/simconnect Go library (currently v0.31.3), embedded at the library version the server is built against. The server is cross-platform in this mode — no simulator installation is required.

Tools are called over the Model Context Protocol using JSON-RPC 2.0 with the tools/call method. Error responses are returned as text content (not JSON-RPC errors) with a prefix token followed by a colon and a human-readable message.

Tool Overview

Pagination

All paginated list_* tools (every list_* tool except list_simvar_categories and list_library_guides, which return their full result in one response) return a Page[T] envelope with the following fields:

Live scraping confirmation

When the server runs with DOCS_LIVE_SCRAPE=true (see Configuration), the twelve SDK reference tools (SimVars, events, functions, structures, error codes and search_docs) take one more parameter:

Without it, these tools answer with a request to confirm and retry. The three library guide tools never need it. /health reports the setting as live_scrape.

SimVars

list_simvar_categories

List all SimVar category filter values. Use these exact strings as the category parameter of list_simvars. Note that some categories contain / without spaces (e.g. "AIRCRAFT AUTOPILOT/ASSISTANT VARIABLES") while others use / with spaces (e.g. "AIRCRAFT BRAKE / LANDING GEAR VARIABLES") — copy them verbatim.

Parameters

None.

Returns

An object with the following fields:

Example request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "tools/call",
  "params": {
    "name": "list_simvar_categories",
    "arguments": {}
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"total\":2,\"categories\":[\"AIRCRAFT AUTOPILOT/ASSISTANT VARIABLES\",\"AIRCRAFT BRAKE / LANDING GEAR VARIABLES\"]}"
      }
    ]
  }
}

Error codes

• INTERNAL_ERROR: Unexpected store failure.

list_simvars

List SimConnect simulation variables, optionally filtered by category, with pagination.

Parameters

Returns

A Page[SimVar] object. Each SimVar has:

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_simvars",
    "arguments": {
      "category": "Aircraft Position and Speed",
      "page": 1,
      "page_size": 5
    }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"items\":[{\"name\":\"PLANE ALTITUDE\",\"description\":\"The altitude of the aircraft above mean sea level.\",\"units\":[\"feet\",\"meters\"],\"settable\":false,\"category\":\"Aircraft Position and Speed\",\"versions\":[\"2020\",\"2024\"],\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/SimVars/Aircraft_SimVars/Aircraft_Position_And_Speed_Variables.htm\"},{\"name\":\"GROUND ALTITUDE\",\"description\":\"Altitude of the ground directly below the aircraft.\",\"units\":[\"feet\",\"meters\"],\"settable\":false,\"category\":\"Aircraft Position and Speed\",\"versions\":[\"2020\",\"2024\"],\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/SimVars/Aircraft_SimVars/Aircraft_Position_And_Speed_Variables.htm\"}],\"page\":1,\"page_size\":5,\"total_items\":2,\"total_pages\":1}"
      }
    ]
  }
}

Error codes

• INVALID_PAGE: page is less than 1, or page_size is less than 1 or greater than 100.
• INTERNAL_ERROR: Unexpected store failure.

get_simvar

Fetch a single SimConnect simulation variable by name (case-insensitive).

Parameters

Returns

A single SimVar object. See list_simvars for field descriptions.

Example request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_simvar",
    "arguments": {
      "name": "PLANE ALTITUDE"
    }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"name\":\"PLANE ALTITUDE\",\"description\":\"The altitude of the aircraft above mean sea level.\",\"units\":[\"feet\",\"meters\"],\"settable\":false,\"category\":\"Aircraft Position and Speed\",\"versions\":[\"2020\",\"2024\"],\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/SimVars/Aircraft_SimVars/Aircraft_Position_And_Speed_Variables.htm\"}"
      }
    ]
  }
}

Error codes

• NOT_FOUND: No SimVar with the given name exists in the corpus.
• INTERNAL_ERROR: Unexpected store failure.

Events

list_events

List SimConnect client input events (Key Event IDs) with pagination.

Parameters

Returns

A Page[Event] object. Each Event has:

Each EventParam has:

Example request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_events",
    "arguments": {
      "page": 1,
      "page_size": 20
    }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"items\":[{\"name\":\"BRAKES\",\"description\":\"Apply or release the aircraft brakes.\",\"versions\":[\"2020\",\"2024\"],\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/Event_IDs/Aircraft_Misc_Events.htm\"},{\"name\":\"THROTTLE_SET\",\"description\":\"Set throttle to a specific position.\",\"parameters\":[{\"index\":0,\"name\":\"Value\",\"description\":\"Throttle position (0\u201316383).\",\"type\":\"DWORD\"}],\"versions\":[\"2020\",\"2024\"],\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/Event_IDs/Aircraft_Engine_Events.htm\"}],\"page\":1,\"page_size\":20,\"total_items\":2,\"total_pages\":1}"
      }
    ]
  }
}

Error codes

• INVALID_PAGE: page is less than 1, or page_size is less than 1 or greater than 100.
• INTERNAL_ERROR: Unexpected store failure.

get_event

Fetch a single SimConnect client input event by name (case-insensitive).

Parameters

Returns

A single Event object. See list_events for field descriptions.

Example request

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_event",
    "arguments": {
      "name": "THROTTLE_SET"
    }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"name\":\"THROTTLE_SET\",\"description\":\"Set throttle to a specific position.\",\"parameters\":[{\"index\":0,\"name\":\"Value\",\"description\":\"Throttle position (0\u201316383).\",\"type\":\"DWORD\"}],\"versions\":[\"2020\",\"2024\"],\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/Event_IDs/Aircraft_Engine_Events.htm\"}"
      }
    ]
  }
}

Error codes

• NOT_FOUND: No event with the given name exists in the corpus.
• INTERNAL_ERROR: Unexpected store failure.

Functions

list_functions

List SimConnect C API functions with pagination.

Parameters

Returns

A Page[Function] object. Each Function has:

Each FunctionParam has:

Example request

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "list_functions",
    "arguments": {
      "page": 1,
      "page_size": 20
    }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"items\":[{\"name\":\"SimConnect_Open\",\"description\":\"Opens a new connection with the SimConnect server.\",\"signature\":\"SIMCONNECTAPI SimConnect_Open(HANDLE * phSimConnect, LPCSTR szName, HWND hWnd, DWORD UserEventWin32, HANDLE hEventHandle, DWORD ConfigIndex)\",\"parameters\":[{\"name\":\"phSimConnect\",\"type\":\"HANDLE *\",\"direction\":\"out\",\"description\":\"Pointer to a handle to receive the new connection.\"},{\"name\":\"szName\",\"type\":\"LPCSTR\",\"direction\":\"in\",\"description\":\"Application name string.\"}],\"return_type\":\"HRESULT\",\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/SimConnect/API_Reference/General/SimConnect_Open.htm\"},{\"name\":\"SimConnect_Close\",\"description\":\"Closes the connection to the SimConnect server.\",\"signature\":\"SIMCONNECTAPI SimConnect_Close(HANDLE hSimConnect)\",\"parameters\":[{\"name\":\"hSimConnect\",\"type\":\"HANDLE\",\"direction\":\"in\",\"description\":\"The handle returned by SimConnect_Open.\"}],\"return_type\":\"HRESULT\",\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/SimConnect/API_Reference/General/SimConnect_Close.htm\"}],\"page\":1,\"page_size\":20,\"total_items\":2,\"total_pages\":1}"
      }
    ]
  }
}

Error codes

• INVALID_PAGE: page is less than 1, or page_size is less than 1 or greater than 100.
• INTERNAL_ERROR: Unexpected store failure.

get_function

Fetch a single SimConnect API function by name (case-insensitive).

Parameters

Returns

A single Function object. See list_functions for field descriptions.

Example request

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "get_function",
    "arguments": {
      "name": "SimConnect_Open"
    }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"name\":\"SimConnect_Open\",\"description\":\"Opens a new connection with the SimConnect server.\",\"signature\":\"SIMCONNECTAPI SimConnect_Open(HANDLE * phSimConnect, LPCSTR szName, HWND hWnd, DWORD UserEventWin32, HANDLE hEventHandle, DWORD ConfigIndex)\",\"parameters\":[{\"name\":\"phSimConnect\",\"type\":\"HANDLE *\",\"direction\":\"out\",\"description\":\"Pointer to a handle to receive the new connection.\"},{\"name\":\"szName\",\"type\":\"LPCSTR\",\"direction\":\"in\",\"description\":\"Application name string.\"}],\"return_type\":\"HRESULT\",\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/SimConnect/API_Reference/General/SimConnect_Open.htm\"}"
      }
    ]
  }
}

Error codes

• NOT_FOUND: No function with the given name exists in the corpus.
• INTERNAL_ERROR: Unexpected store failure.

Structures

list_structures

List SimConnect C data structures with pagination.

Parameters

Returns

A Page[Structure] object. Each Structure has:

Each StructField has:

Example request

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "list_structures",
    "arguments": {
      "page": 1,
      "page_size": 20
    }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"items\":[{\"name\":\"SIMCONNECT_RECV\",\"description\":\"Base structure for all data received from SimConnect.\",\"fields\":[{\"name\":\"dwSize\",\"type\":\"DWORD\",\"description\":\"Size of the structure in bytes.\"},{\"name\":\"dwVersion\",\"type\":\"DWORD\",\"description\":\"SimConnect version number.\"},{\"name\":\"dwID\",\"type\":\"DWORD\",\"description\":\"ID identifying the type of the received data packet.\"}],\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/SimConnect/API_Reference/Structures_And_Enumerations/SIMCONNECT_RECV.htm\"},{\"name\":\"SIMCONNECT_DATA_INITPOSITION\",\"description\":\"Defines an aircraft initial position and state.\",\"fields\":[{\"name\":\"Latitude\",\"type\":\"double\",\"description\":\"Latitude in degrees.\"},{\"name\":\"Longitude\",\"type\":\"double\",\"description\":\"Longitude in degrees.\"},{\"name\":\"Altitude\",\"type\":\"double\",\"description\":\"Altitude in feet.\"}],\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/SimConnect/API_Reference/Structures_And_Enumerations/SIMCONNECT_DATA_INITPOSITION.htm\"}],\"page\":1,\"page_size\":20,\"total_items\":2,\"total_pages\":1}"
      }
    ]
  }
}

Error codes

• INVALID_PAGE: page is less than 1, or page_size is less than 1 or greater than 100.
• INTERNAL_ERROR: Unexpected store failure.

get_structure

Fetch a single SimConnect data structure by name (case-insensitive).

Parameters

Returns

A single Structure object. See list_structures for field descriptions.

Example request

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "get_structure",
    "arguments": {
      "name": "SIMCONNECT_DATA_INITPOSITION"
    }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"name\":\"SIMCONNECT_DATA_INITPOSITION\",\"description\":\"Defines an aircraft initial position and state.\",\"fields\":[{\"name\":\"Latitude\",\"type\":\"double\",\"description\":\"Latitude in degrees.\"},{\"name\":\"Longitude\",\"type\":\"double\",\"description\":\"Longitude in degrees.\"},{\"name\":\"Altitude\",\"type\":\"double\",\"description\":\"Altitude in feet.\"}],\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/SimConnect/API_Reference/Structures_And_Enumerations/SIMCONNECT_DATA_INITPOSITION.htm\"}"
      }
    ]
  }
}

Error codes

• NOT_FOUND: No structure with the given name exists in the corpus.
• INTERNAL_ERROR: Unexpected store failure.

Error Codes

list_error_codes

List SIMCONNECT_EXCEPTION enumeration values with pagination.

Parameters

Returns

A Page[ErrorCode] object. Each ErrorCode has:

Example request

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "list_error_codes",
    "arguments": {
      "page": 1,
      "page_size": 20
    }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"items\":[{\"name\":\"SIMCONNECT_EXCEPTION_NONE\",\"value\":0,\"description\":\"No error.\",\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/SimConnect/API_Reference/Structures_And_Enumerations/SIMCONNECT_EXCEPTION.htm\"},{\"name\":\"SIMCONNECT_EXCEPTION_ERROR\",\"value\":1,\"description\":\"Unspecified error.\",\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/SimConnect/API_Reference/Structures_And_Enumerations/SIMCONNECT_EXCEPTION.htm\"}],\"page\":1,\"page_size\":20,\"total_items\":2,\"total_pages\":1}"
      }
    ]
  }
}

Error codes

• INVALID_PAGE: page is less than 1, or page_size is less than 1 or greater than 100.
• INTERNAL_ERROR: Unexpected store failure.

get_error_code

Fetch a single SIMCONNECT_EXCEPTION enum value by name or by integer value. At least one of name or value must be provided.

When both name and value are provided, name lookup is attempted first. If name lookup fails, the tool falls back to scanning by integer value.

Parameters

At least one of name or value must be supplied. Providing neither returns an INVALID_ARGUMENT error. Providing both causes a name lookup first, with value as fallback.

Returns

A single ErrorCode object. See list_error_codes for field descriptions.

Example request (by name)

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "get_error_code",
    "arguments": {
      "name": "SIMCONNECT_EXCEPTION_NONE"
    }
  }
}

Example request (by value)

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "get_error_code",
    "arguments": {
      "value": 1
    }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"name\":\"SIMCONNECT_EXCEPTION_NONE\",\"value\":0,\"description\":\"No error.\",\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/SimConnect/API_Reference/Structures_And_Enumerations/SIMCONNECT_EXCEPTION.htm\"}"
      }
    ]
  }
}

Error codes

• INVALID_ARGUMENT: Neither name nor value was provided.
• NOT_FOUND: No error code matching the given name or value exists in the corpus.
• INTERNAL_ERROR: Unexpected store failure.

Search

search_docs

Full-text search across the SimConnect documentation corpus. Returns matching SimVars, events, functions, structures, and error codes with ranked excerpts.

Parameters

Returns

A SearchResults object with the following fields:

Each SearchResult has:

Example request

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "search_docs",
    "arguments": {
      "query": "altitude",
      "type": "simvar",
      "limit": 5
    }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 12,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"query\":\"altitude\",\"total\":2,\"results\":[{\"type\":\"simvar\",\"name\":\"PLANE ALTITUDE\",\"excerpt\":\"The altitude of the aircraft above mean sea level.\",\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/SimVars/Aircraft_SimVars/Aircraft_Position_And_Speed_Variables.htm\"},{\"type\":\"simvar\",\"name\":\"GROUND ALTITUDE\",\"excerpt\":\"Altitude of the ground directly below the aircraft.\",\"source_url\":\"https://docs.flightsimulator.com/html/Programming_Tools/SimVars/Aircraft_SimVars/Aircraft_Position_And_Speed_Variables.htm\"}]}"
      }
    ]
  }
}

Error codes

• INVALID_ARGUMENT: query is empty or whitespace-only, type is not one of the allowed values, or limit is less than 1 or greater than 100.
• INTERNAL_ERROR: Unexpected store failure.

Library Guides

These three tools serve the guides of the github.com/mrlm-net/simconnect Go library — the SimConnect client and manager, facilities, input events, client data areas, pkg/airport (ground layouts, taxi routing, SID/STAR/approach procedures), pkg/nav (airways, weather, active runway, ATIS, flight plans), pkg/traffic (AI traffic, departures, arrivals, schedules, sequencing, separation, radio), pkg/camera (add-on camera), pkg/systems (aircraft systems profiles), pkg/avionics (radios and transponder) and pkg/addons (installed add-ons). The 46 guides are embedded in the server binary at the library version go.mod requires (currently v0.31.3), so they always match the library the server is built with. In docs and both modes the /health endpoint reports that version as library_version.

Each guide is split into chapters at its ## headings. The usual flow is search_library_docs or list_library_guides to find a guide, then get_library_guide with a chapter to read only the relevant part — whole guides can be long.

list_library_guides

List the library guides, optionally filtered by section, with the chapter headings of each guide.

Parameters

Returns

An object with the following fields:

Each Guide has:

Example request

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "list_library_guides",
    "arguments": {
      "section": "airport"
    }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 13,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"library\":\"github.com/mrlm-net/simconnect\",\"version\":\"v0.31.3\",\"total\":1,\"guides\":[{\"slug\":\"airport-layout\",\"title\":\"Airport Layout & Taxi Routing\",\"description\":\"Load an airport's ground layout with pkg/airport and compute taxi routes between stands and runways.\",\"section\":\"airport\",\"chapters\":[\"Loading a layout\",\"The Layout model\",\"Taxi graph and routes\",\"GeoJSON\",\"Procedures: SIDs, STARs, approaches\",\"Airport limits\",\"Which airport an aircraft is at\",\"Seeing it on a map\"]}]}"
      }
    ]
  }
}

Error codes

• NOT_FOUND: No guides in the given section. The message lists the valid sections.

get_library_guide

Read a library guide as Markdown — the whole guide, or a single ## chapter of it.

Parameters

Returns

Plain Markdown text (not JSON). Without chapter: the guide title as a # heading followed by the full guide. With chapter: the guide title, the chapter’s ## heading, and that chapter’s text.

Example request

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "get_library_guide",
    "arguments": {
      "slug": "airport-layout",
      "chapter": "Taxi graph"
    }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 14,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Airport Layout & Taxi Routing\n\n## Taxi graph and routes\n\n..."
      }
    ]
  }
}

Error codes

• NOT_FOUND: No guide with the given slug, or the guide has no chapter matching chapter (no exact match and not a unique prefix). The chapter error message lists the guide’s chapter headings.

search_library_docs

Search the library guides chapter by chapter. Every word of the query must appear in the chapter text, the chapter heading, or the guide’s title or description — order-independent and case-insensitive. Results are ranked best first: words found in a chapter heading weigh most, then words in the guide title, then occurrences in the text. Go identifiers and concepts work well as queries (e.g., "RouteToRunway", "holding pattern", "wake separation", "weather reader").

Parameters

Returns

An object with the following fields:

Each LibraryHit has:

Example request

{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "tools/call",
  "params": {
    "name": "search_library_docs",
    "arguments": {
      "query": "taxi route",
      "limit": 3
    }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 15,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"query\":\"taxi route\",\"total\":1,\"results\":[{\"slug\":\"airport-layout\",\"title\":\"Airport Layout & Taxi Routing\",\"heading\":\"Taxi graph and routes\",\"excerpt\":\"…\"}]}"
      }
    ]
  }
}

Error codes

• INVALID_ARGUMENT: query is empty or whitespace-only, or limit is less than 1 or greater than 50.