MCP Tools — SimConnect Mode

All 19 MCP tools listed here are available when the server runs with MCP_MODE=simconnect. This mode provides live simulator data via the SimConnect SDK.

Requirements: Windows only. Microsoft Flight Simulator 2020 or 2024 must be running with SimConnect enabled before issuing any read or transmit calls. The get_sim_state tool is safe to call at any time regardless of connection state.

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

get_simvar_value

Read a single live simulation variable from the running simulator.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns

Example request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_simvar_value",
    "arguments": {
      "name": "PLANE ALTITUDE",
      "unit": "feet"
    }
  }
}

Example response (connected)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"name\":\"PLANE ALTITUDE\",\"value\":5280.0,\"unit\":\"feet\",\"sim_time\":3742.5}"
      }
    ]
  }
}

Example response (disconnected)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "BRIDGE_DISCONNECTED: no active simulator connection"
      }
    ],
    "isError": true
  }
}

Error codes

• BRIDGE_DISCONNECTED: The SimConnect bridge is not connected to the simulator. Start the simulator and ensure SimConnect is enabled.
• INVALID_ARGUMENT: name or unit was not provided or is empty.
• UNKNOWN_VARIABLE: The variable name or unit is not recognised by SimConnect. Check the name against the SimConnect SDK reference.
• INTERNAL_ERROR: Unexpected bridge or SimConnect failure.

get_simvar_values

Read up to 20 live simulation variables in a single call. Per-item failures are embedded in the response array and do not abort the batch.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns

An array of result objects. Each object has:

Example request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_simvar_values",
    "arguments": {
      "vars": [
        { "name": "PLANE ALTITUDE", "unit": "feet" },
        { "name": "AIRSPEED INDICATED", "unit": "knots" }
      ]
    }
  }
}

Example response (connected)

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"name\":\"PLANE ALTITUDE\",\"value\":5280.0,\"unit\":\"feet\",\"sim_time\":3742.5},{\"name\":\"AIRSPEED INDICATED\",\"value\":142.3,\"unit\":\"knots\",\"sim_time\":3742.5}]"
      }
    ]
  }
}

Error codes

• BRIDGE_DISCONNECTED: The SimConnect bridge is not connected to the simulator.
• INVALID_ARGUMENT: vars was not provided, is empty, exceeds 20 items, or contains an item missing name or unit.
• UNKNOWN_VARIABLE: One or more variable names or units in the batch are not recognised by SimConnect.
• INTERNAL_ERROR: Unexpected bridge or SimConnect failure.

transmit_event

Transmit a named SimConnect client event to the running simulator.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns

Example request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "transmit_event",
    "arguments": {
      "name": "LANDING_LIGHTS_TOGGLE"
    }
  }
}

Example response (connected)

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"event\":\"LANDING_LIGHTS_TOGGLE\",\"success\":true,\"value\":0}"
      }
    ]
  }
}

Example response (disconnected)

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "BRIDGE_DISCONNECTED: no active simulator connection"
      }
    ],
    "isError": true
  }
}

Error codes

• BRIDGE_DISCONNECTED: The SimConnect bridge is not connected to the simulator.
• INVALID_ARGUMENT: name was not provided or is empty, or value is not an integer in the range [0, 4294967295].
• INTERNAL_ERROR: Unexpected bridge or SimConnect failure.

get_sim_state

Return a snapshot of current simulator connection state and flight status. This tool never returns an error — it returns {"connected": false} when the bridge is not connected, allowing clients to safely poll at any connection state.

Requirements: Windows. The simulator does not need to be running.

Parameters: None.

Returns

Example request

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

Example response (connected)

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"connected\":true,\"current_flight\":\"LAST.FLT\",\"paused\":false,\"sim_time\":3742.5,\"simulator_version\":\"11.0.282174.0\"}"
      }
    ]
  }
}

Example response (disconnected)

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"connected\":false}"
      }
    ],
    "isError": false
  }
}

Error codes: None. This tool always succeeds.

set_simvar_value

Write a numeric simulation variable to the user aircraft. Only writable SimVars will take effect. Use get_simvar (docs mode) to check whether a variable is settable before calling this tool.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns

Example request

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "set_simvar_value",
    "arguments": {
      "name": "AUTOPILOT ALTITUDE LOCK VAR",
      "unit": "feet",
      "value": 10000
    }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"name\":\"AUTOPILOT ALTITUDE LOCK VAR\",\"success\":true,\"unit\":\"feet\",\"value\":10000}"
      }
    ]
  }
}

Error codes

• BRIDGE_DISCONNECTED: The SimConnect bridge is not connected to the simulator.
• INVALID_ARGUMENT: name, unit, or value was not provided or has the wrong type.
• INTERNAL_ERROR: Unexpected bridge or SimConnect failure.

get_nearby_traffic

Return a list of AI and player aircraft within a given radius of the user aircraft. The player aircraft is always included. Returns position, heading, speed, and on-ground status for each aircraft.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns

Each entry in traffic:

Example request

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "get_nearby_traffic",
    "arguments": { "radius_meters": 50000 }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"count\":2,\"radius_meters\":50000,\"traffic\":[{\"object_id\":1,\"title\":\"Airbus A320 Neo\",\"atc_id\":\"TAP123\",\"atc_airline\":\"TAP Air Portugal\",\"latitude\":38.77,\"longitude\":-9.13,\"altitude_ft\":8200,\"true_heading_deg\":274.0,\"ground_speed_kts\":210.5,\"on_ground\":false}]}"
      }
    ]
  }
}

Error codes: None. Errors (not connected, scan failure) are embedded as an error field in the response body rather than returned as MCP errors.

get_traffic_with_phase

Return nearby aircraft with enriched telemetry: vertical speed, actual ground track, inferred flight phase, parking state, runway occupancy, and aircraft category. Uses a single SimConnect round-trip with the same latency as get_nearby_traffic.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns

Each entry in traffic (all fields from get_nearby_traffic plus):

Example request

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "get_traffic_with_phase",
    "arguments": {}
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"count\":1,\"radius_meters\":25000,\"traffic\":[{\"object_id\":1,\"title\":\"Cessna 172\",\"atc_id\":\"N12345\",\"atc_airline\":\"\",\"category\":\"Prop\",\"latitude\":38.77,\"longitude\":-9.13,\"altitude_ft\":4500,\"true_heading_deg\":090.0,\"track_deg\":088.5,\"ground_speed_kts\":110.0,\"vertical_speed_fpm\":-200,\"on_ground\":false,\"in_parking_state\":false,\"on_any_runway\":false,\"flight_phase\":\"DESCENT\"}]}"
      }
    ]
  }
}

Error codes: None. Errors are embedded in the response body.

get_airports_in_range

Return a list of airports in the simulator’s loaded scenery area (reality bubble), sorted by distance from the player aircraft. By default only standard ICAO-format airports are returned.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns

Each entry in airports:

Example request

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "get_airports_in_range",
    "arguments": { "radius_km": 100 }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"airports\":[{\"icao\":\"LPMA\",\"region\":\"LP\",\"latitude\":32.697,\"longitude\":-16.778,\"altitude_m\":58.0,\"distance_km\":0.3},{\"icao\":\"LPCC\",\"region\":\"LP\",\"latitude\":32.699,\"longitude\":-16.645,\"altitude_m\":98.0,\"distance_km\":14.9}],\"count\":2,\"expanded\":false,\"radius_km\":100}"
      }
    ]
  }
}

Error codes: None. Errors are embedded in the response body.

get_nearest_airport

Return the single closest airport to the player aircraft. Note: SimConnect’s facility list APIs may exclude the airport the player is currently on; use get_airports_in_range with expanded=true if you need to detect the current airport.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters: None.

Returns

An airport entry object with the same fields as entries returned by get_airports_in_range, or an object with an error field when not connected, no airports are found, or the scan fails.

Example request

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "get_nearest_airport",
    "arguments": {}
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"icao\":\"LPCC\",\"region\":\"LP\",\"latitude\":32.699,\"longitude\":-16.645,\"altitude_m\":98.0,\"distance_km\":14.9}"
      }
    ]
  }
}

Error codes: None. Errors are embedded in the response body.

get_airport_details

Return detailed facility data for a specific airport by ICAO code. The default response includes name, coordinates, elevation, magnetic variation, closed status, runways, and ATC frequencies. Set expanded=true to also receive parking stands, helipads, instrument approaches, SIDs, and STARs.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns (default)

Additional fields when expanded=true

Example request

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "get_airport_details",
    "arguments": { "icao": "LPMA" }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"icao\":\"LPMA\",\"region\":\"LP\",\"name\":\"Madeira\",\"name64\":\"Cristiano Ronaldo International Airport\",\"latitude\":32.697,\"longitude\":-16.778,\"altitude_m\":58.0,\"magvar_deg\":-5.2,\"is_closed\":false,\"runway_count\":1,\"runways\":[{\"name\":\"05/23\",\"heading_deg\":54.0,\"length_m\":2781,\"width_m\":45,\"surface\":\"Asphalt\"}],\"frequencies\":[{\"type\":\"ATIS\",\"freq_mhz\":126.9,\"name\":\"Madeira ATIS\"}]}"
      }
    ]
  }
}

Error codes

• BRIDGE_DISCONNECTED: Not connected to the simulator.
• INVALID_ARGUMENT: icao must be 1–9 uppercase alphanumeric characters; region must be 0–4 uppercase alphanumeric characters.
• AIRPORT_NOT_FOUND: No airport matching the given ICAO code was found.
• AIRPORT_DETAILS_ERROR: SimConnect returned an error while fetching facility data.

get_vors_in_range

Return a list of VOR navigation stations in the simulator’s reality bubble, sorted by distance from the player aircraft.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns

Each entry in vors:

Error codes: None. Errors (not connected) are embedded as an error field in the response body.

get_vor_details

Return detailed data for a specific VOR navigation station by ICAO code.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns

Error codes

• BRIDGE_DISCONNECTED: Not connected to the simulator.
• INVALID_ARGUMENT: icao was not provided or is empty.
• VOR_NOT_FOUND: No VOR matching the given ICAO code was found.

get_ndbs_in_range

Return a list of NDB navigation stations in the simulator’s reality bubble, sorted by distance from the player aircraft.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns

Each entry in ndbs:

Error codes: None. Errors are embedded as an error field in the response body.

get_ndb_details

Return detailed data for a specific NDB navigation station by ICAO code.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns

Error codes

• BRIDGE_DISCONNECTED: Not connected to the simulator.
• INVALID_ARGUMENT: icao was not provided or is empty.
• NDB_NOT_FOUND: No NDB matching the given ICAO code was found.

get_waypoints_in_range

Return a list of waypoints in the simulator’s reality bubble, sorted by distance from the player aircraft.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns

Each entry in waypoints:

Error codes: None. Errors are embedded as an error field in the response body.

get_waypoint_details

Return detailed data for a specific waypoint by ICAO code.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns

Error codes

• BRIDGE_DISCONNECTED: Not connected to the simulator.
• INVALID_ARGUMENT: icao must be 1–9 uppercase alphanumeric characters; region must be 0–4 uppercase alphanumeric characters.
• WAYPOINT_NOT_FOUND: No waypoint matching the given ICAO code was found.

get_airport_taxiways

Return the taxiway network graph for a specific airport by ICAO code. The response contains three correlated arrays: names (taxiway letter strings), paths (directed edges referencing start/end node indices and a name index), and points (graph nodes including hold-short positions). Leave region empty for best results.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns

Each entry in paths:

Each entry in points:

Example request

{
  "jsonrpc": "2.0",
  "id": 17,
  "method": "tools/call",
  "params": {
    "name": "get_airport_taxiways",
    "arguments": { "icao": "EDDM" }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 17,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"names\":[\"A\",\"B\",\"N\"],\"paths\":[{\"type\":\"TAXIWAY\",\"width_m\":23.0,\"start_node\":0,\"end_node\":1,\"name_index\":0,...}],\"points\":[{\"type\":\"NORMAL\",\"orientation\":\"NONE\",\"bias_x_m\":-823.5,\"bias_z_m\":441.2}]}"
      }
    ]
  }
}

Error codes

• BRIDGE_DISCONNECTED: Not connected to the simulator.
• INVALID_ARGUMENT: icao must be 1–9 uppercase alphanumeric characters; region must be 0–4 uppercase alphanumeric characters.
• TAXIWAY_NOT_FOUND: No taxiway data was found for the given ICAO code.
• TAXIWAY_ERROR: SimConnect returned an error while fetching taxiway data.

get_taxiway_names

Return only the taxiway letter/name strings for an airport by ICAO code. Lightweight alternative to get_airport_taxiways when only the taxiway label list is needed — no paths or points are returned.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns

Example request

{
  "jsonrpc": "2.0",
  "id": 19,
  "method": "tools/call",
  "params": {
    "name": "get_taxiway_names",
    "arguments": { "icao": "EDDM" }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 19,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"icao\":\"EDDM\",\"name_count\":12,\"names\":[\"A\",\"B\",\"C\",\"D\",\"E\",\"F\",\"G\",\"H\",\"J\",\"K\",\"M\",\"N\"]}"
      }
    ]
  }
}

Error codes

• BRIDGE_DISCONNECTED: Not connected to the simulator.
• INVALID_ARGUMENT: icao must be 1–9 uppercase alphanumeric characters; region must be 0–4 uppercase alphanumeric characters.
• TAXIWAY_NOT_FOUND: No taxiway data was found for the given ICAO code.
• TAXIWAY_ERROR: SimConnect returned an error while fetching taxiway data.

get_airport_parkings

Return all parking stands, gates, and ramps at a specific airport by ICAO code. Each entry includes type, name, suffix, number, heading, radius, and position offsets from the airport reference point. Returns the full TAXI_PARKING record — more fields than the abbreviated stands array in get_airport_details. Leave region empty for best results.

Requirements: Windows + MSFS 2020 or 2024 running with SimConnect enabled.

Parameters

Returns

Each entry in parkings:

Example request

{
  "jsonrpc": "2.0",
  "id": 18,
  "method": "tools/call",
  "params": {
    "name": "get_airport_parkings",
    "arguments": { "icao": "EDDM" }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": 18,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"count\":2,\"parkings\":[{\"type\":\"GATE\",\"name\":\"Gate\",\"suffix\":\"A\",\"number\":1,\"orientation\":\"NONE\",\"heading_deg\":180.0,\"radius_m\":40.0,\"bias_x_m\":120.5,\"bias_z_m\":-310.2},{\"type\":\"RAMP_GA\",\"name\":\"Ramp GA\",\"suffix\":\"\",\"number\":2,\"orientation\":\"NONE\",\"heading_deg\":90.0,\"radius_m\":12.0,\"bias_x_m\":-50.0,\"bias_z_m\":80.0}]}"
      }
    ]
  }
}

Error codes

• BRIDGE_DISCONNECTED: Not connected to the simulator.
• INVALID_ARGUMENT: icao must be 1–9 uppercase alphanumeric characters; region must be 0–4 uppercase alphanumeric characters.
• PARKING_NOT_FOUND: No parking data was found for the given ICAO code.
• PARKING_ERROR: SimConnect returned an error while fetching parking data.