SimConnect MCP

Browse the aircraft L-var catalogs. Three levels, narrowing as you supply arguments: * no catalog resolved -- every available aircraft catalog * catalog only -- the panels in that catalog * catalog+panel -- the variables on that panel, with their valid values With no 'catalog', the loaded aircraft is auto-detected: PMDG's own client-data-area probe first (authoritative -- confirms which SDK is actually running, independent of what TITLE/ATC_MODEL say), then every catalog's own title_pattern matched against TITLE/ATC_MODEL (the only mechanism for a third-party catalog dropped into data/). A successful detection acts as if that catalog had been passed explicitly, and 'message' names which of the two resolved it -- a probed detection is a materially stronger signal than a title-text match. When detection fails entirely, 'catalog' comes back None, 'message' explains why, and (with 'panel' also given) the panel is looked up across every catalog -- the first match is returned, but that is a guess, not a detection, and 'message' says so.

Establish SimConnect connection to MSFS. Must be called before using any other tools. Automatically attempts to load MobiFlight WASM extension for L-var support.

Spawn an AI aircraft or object at a position. Useful for building traffic or collision-avoidance test scenarios. The title must match an installed aircraft exactly. When it does, SimConnect confirms the object was actually created with an ASSIGNED_OBJECT_ID reply, and `object_id` on the result carries it -- also the id SimConnect_AIRemoveObject would need to remove it again. When the title matches nothing installed, MSFS ignores the request silently: no error, no reply, so `object_id` stays null. Treat that null as "not confirmed to exist," not as a definite failure of this call -- a request registry being briefly slow to answer, or a connection with none at all (the plain SimConnect fallback), leaves the same null for a different reason; see `message` for which applies.

Close the SimConnect connection to MSFS.

Execute RPN calculator code in the simulator. Runs arbitrary RPN (Reverse Polish Notation) calculator code via the MobiFlight WASM bridge. Can read or write any variable type and perform complex operations. Requires the MobiFlight WASM extension. The 'auto' mode's heuristic -- code starts with '(', ends with ')', and contains no '(>' -- misclassifies compound read expressions such as '(L:A) (L:B) max' as an execute, because they don't end in ')'. Pass mode='read' explicitly for those.

Read a snapshot of the current aircraft state. Narrow with 'sections' to keep the response small -- for example sections=['position'] for a position fix, or ['engines', 'systems'] when debugging a systems issue. All variables across the chosen sections are read in a single batched call.

Check SimConnect connection state, whether sim is running/paused.

Look up one airport, waypoint, NDB or VOR by ICAO identifier. Only facilities the sim currently has loaded are visible. Airports are the exception: SimConnect's airport facility list is the complete worldwide set (measured live -- see module docstring), not scoped to the aircraft's location, so an airport miss means the identifier is wrong rather than out of range.

Read an L-var (local variable) value from the current aircraft. L-vars are aircraft-specific local variables used by add-on developers. Requires the MobiFlight WASM extension.

List airports near a point, nearest first. Filters SimConnect's airport facility list by great-circle distance from the given (or current) position. That list is not scoped to the aircraft's location at all -- measured live, it is the entire world (85,249 airports) regardless of where the aircraft is -- so a radius that finds nothing means there is genuinely no airport that close, not that the sim "hasn't loaded" one. The distance filter always runs over the complete list before pagination, so a later page can never miss a match an earlier page's filtering already found.

Read a PMDG CDU screen (777 has 3 CDUs, 737 NG3 has 2). Returns the CDU display as text rows and an optional structured grid with per-cell color and formatting information. Requires ``EnableCDUBroadcast.N=1`` in the aircraft's options.ini.

Read a PMDG aircraft data field by name (777 or 737 NG3). Uses the PMDG SDK data broadcast to read switch positions, annunciators, knob positions, MCP values, fuel quantities, FMC data, and more. Requires ``EnableDataBroadcast=1`` in the aircraft's options.ini (``777_Options.ini`` or ``737NG3_Options.ini``).

Read a SimVar value by name, in the requested unit. Returns the value together with the unit it was actually read in. Use msfs_search_simvars first if you are unsure of the exact name or units.

Read several SimVars in one call. Results are keyed by 'NAME' or 'NAME:index'. A failure on one variable does not abort the others -- that entry carries an 'error' instead.

List the aircraft that HubHop has presets for. Use this to find the exact vendor and aircraft spelling to pass to msfs_search_hubhop -- HubHop matches those filters exactly, so getting the spelling from here first avoids a filtered search that silently finds nothing because of a mismatched name. Like msfs_search_hubhop, the first call in this server's session downloads the full preset database (roughly 32,000 presets, ~17 MB), which can take several seconds; the two tools share the same in-memory copy afterwards, refreshed automatically every 6 hours. Pass refresh=True to force an immediate re-fetch instead of waiting on that. Requires internet access.

Enumerate the L-vars registered by the currently loaded aircraft. Asks the MobiFlight WASM module for its L-var list and collects the response. The module caps its reply at 1000 names but still reports the list as complete when it does -- see 'truncated' in the result, which is set whenever that cap was hit. A busy add-on setup (e.g. GSX) can crowd an aircraft's own L-vars out of a capped response entirely; msfs_get_lvar reads any name directly regardless of whether it showed up here. Returns bare names only -- no description, category, or writability per variable, unlike msfs_search_lvars' catalogued rows. Use msfs_search_lvars / msfs_browse_lvar_catalog for aircraft with a bundled catalog when that detail is what you need; use this tool for aircraft that have none, or to see everything currently registered regardless of catalog coverage. Internally sends a harmless no-op RPN command immediately before the WASM request, to re-arm the module against a quirk where it otherwise gives no response to a request byte-identical to the one it just answered (see _send_list_request's own docstring below for the full story). This creates no variable and has no effect on the aircraft, so calling this repeatedly is safe -- but the underlying quirk is a third-party module behavior this project does not control, so NO_LVARS_RETURNED below stays the honest report for the rare case where even the re-arm doesn't help, rather than this call ever assuming success. Requires the MobiFlight WASM extension. A listing that stops without the module's end-of-list marker returns LVAR_LIST_INCOMPLETE rather than the names collected so far: an arbitrary prefix of the list is indistinguishable from a complete listing of that size once returned, so it is refused the same way msfs_get_nearby_airports refuses a timed-out facility collection.

List every SimVar category with its variable count. Use this to discover category names for the 'category' filter on msfs_search_simvars.

Load a saved flight, replacing the current one. Use this to restore a known starting state before a test run. The current flight is discarded without prompting. Does not return as soon as the load call succeeds -- it waits for MSFS to resume answering SimConnect first (bounded; see _wait_for_sim_responsive and msfs_save_flight's docstring for the measurement behind this). FlightLoad's own stall was short in the one round trip measured live (~0.9s), but a heavier scenery load could take much longer, so this does not assume load is always cheap.

Load a .PLN flight plan into the aircraft's GPS or FMS. The aircraft is not repositioned; only the plan is loaded. Does not return as soon as the load call succeeds -- see msfs_save_flight's docstring and _wait_for_sim_responsive for why this waits (bounded) for MSFS to resume answering SimConnect first.

Save the current flight to a .FLT file. Capture a known state so a later msfs_load_flight call can restore it. Refuses to replace an existing file unless overwrite=True. The library's `sm.save_flight()` ends with an unconditional `return False`, so its return value says nothing about success -- this checks whether the file was actually written instead. Its body also reads the file straight back (flight_to_dic) immediately after issuing an asynchronous FlightSave; if MSFS has not finished writing yet, that read-back can raise rather than return False. Both a clean return and a raised exception are followed by the same polling existence check below, since the file on disk is the only signal either path can be trusted to leave behind. Does not return once the file appears, either. MSFS keeps SimConnect entirely unresponsive for a further ~14s (measured live) while it actually finishes the save; this waits that out too, bounded, so a caller never gets `status: "ok"` while the sim still cannot answer anything -- see _wait_for_sim_responsive's docstring for the full measurement and why the wait is structured the way it is.

Search SimConnect events by keyword, optionally filtered by category. Spans the library's full 994-event catalog, not just the builtin fallback list. Results are paginated.

Search the MobiFlight HubHop community preset database. HubHop covers far more aircraft than the bundled catalogs, so this is the place to look when msfs_search_lvars finds nothing for the loaded aircraft. Each result's `code` field holds RPN -- typically `(>K:...)` or `(>H:...)` -- that you can pass directly to msfs_execute_calculator_code or msfs_trigger_custom_event, so a match here is immediately actionable, not just informational. The first call in this server's session downloads the full preset database (roughly 32,000 presets, ~17 MB) and keeps it in memory; that call alone can take several seconds. This is expected, not a hang. Later calls, including to msfs_list_hubhop_aircraft, reuse the same in-memory copy and return quickly, for up to 6 hours -- after that the next call re-fetches automatically, since HubHop is a community database that keeps growing. Pass refresh=True to force an immediate re-fetch instead of waiting on that, e.g. right after publishing a new preset yourself. Requires internet access. Supply at least one of query, vendor, aircraft or system -- the database is too large to browse unfiltered.

Search known aircraft L-vars by keyword. Searches the embedded L-var catalog for the current aircraft, or every known aircraft catalog if none is loaded or auto-detected. Results are paginated. Auto-detection tries, in order: PMDG's own client-data-area probe (authoritative -- confirms which SDK the aircraft is actually running, independent of what TITLE/ATC_MODEL say), every catalog's own title_pattern matched against TITLE/ATC_MODEL (the only mechanism for a third-party catalog dropped into data/), then honest absence. When no aircraft catalog could be auto-detected and 'catalog' was not given, this searches every catalog ('filters.catalog' reads "all") and 'message' explains how to scope the search instead. Otherwise, 'message' still discloses how the catalog was resolved -- a probed detection is a materially stronger signal than a title-text match, and a caller deciding how much to trust the result should be able to tell them apart. When the search was not scoped to one confirmed catalog, the markdown table also carries a 'Catalog' column per row -- with the Fenix catalog removed, every bundled catalog is PMDG, so a table of PMDG variables must not render as if it were confirmed for whatever aircraft is actually loaded.

Search the SimVar catalog by keyword. Returns each variable's units and whether it is settable, so you can call msfs_get_simvar or msfs_set_simvar with the right arguments. Results are paginated.

Send a PMDG control event (777 or 737 NG3). Triggers cockpit controls (switches, buttons, knobs) using the PMDG SDK event system. Use msfs_search_lvars() to find events — look for entries with an 'events' field.

Display a text overlay message in the simulator (debug feedback).

Reposition the aircraft (test scenario setup). Uses SimConnect's SIMCONNECT_DATA_INITPOSITION, which repositions the aircraft atomically. Writing PLANE_LATITUDE/LONGITUDE individually, as this used to, is unreliable and cannot set the on-ground state. The response reports the position read back from the sim after the move, in `latitude`/`longitude`/etc -- never the request, which is echoed separately under `requested` for comparison. A field the read-back could not confirm is null (and listed in `unverified`), not silently replaced by what was asked for. `status` still reports "ok" since the reposition command itself may well have succeeded even if the confirming read did not; check `unverified`/`warning` for that.

Write a value to an L-var on the current aircraft. Uses native SimConnect data definitions (AddToDataDefinition + SetDataOnSimObject), which works with proprietary aircraft like the Fenix A320/A321. Does NOT require MobiFlight and does NOT use the MobiFlight RPN set() command. Reads the variable back afterwards and reports 'verified': true if the value landed, false if it did not, null if the read-back could not be completed. A false or null is never reported as success.

Write a value to a settable SimVar. Fails with a specific error if the sim rejects the write, rather than reporting success. Check the 'settable' flag with msfs_search_simvars first.

Fire a custom event as a key event through the MobiFlight WASM module. Requires the MobiFlight WASM module. The event is delivered via the WASM module's RPN interface -- `(>K:NAME)`, or `PARAM (>K:NAME)` when a parameter is given -- not through native SimConnect event mapping (that is msfs_trigger_event). This reaches events outside the standard SimConnect catalog. An aircraft with its own event system (PMDG, Fenix) may silently ignore a default key event in favour of its own SDK: measured live against a PMDG 737, `PARKING_BRAKES` delivered through this path had no effect on the aircraft's brake state, while a sim-level event (no aircraft can intercept it) delivered correctly. A no-op result on such aircraft means the aircraft ignored the event, not that this tool failed.

Fire a SimConnect event. Resolves through the library's 994-event catalog first, then falls back to mapping the name directly, so third-party and newer MSFS events work too. Either way, the event is sent through the same MapClientEventToSimEvent + TransmitClientEvent pair, correlated by send ID on a dispatcher-equipped connection (NAME_UNRECOGNIZED/ERROR mean the event doesn't exist; other exceptions propagate as errors). That correlation proves SimConnect accepted the packet -- not that the aircraft acted on it. An aircraft with its own event system (PMDG, Fenix) can silently ignore an event it received in favour of its own SDK; see `message` and CLAUDE.md's "Known Sim Behaviours".

Sample a SimVar over time, returning a time series for debugging. Fails fast if the first read raises, rather than looping for the full duration on a name or unit that will never work.