SimConnect MCP

SimConnect MCP 服务

一个通过 SimConnect 将 AI 编码 Agent 连接到 Microsoft Flight Simulator 的 MCP（Model Context Protocol） 服务。本服务专为附加组件开发打造，可完整读写 SimVar 和 L-var、触发事件、执行计算器代码，并提供内嵌文档。

功能

• 读写任意 SimVar——海拔、航向、速度、自动驾驶设置、发动机参数等；内置完整目录，涵盖 1,080 多个变量，支持选择单位，并在写入被拒时如实报错
• 读写 L-var——附加组件开发者使用的机型专属本地变量（Fenix A320、FlyByWire A32NX、PMDG 等），包括实时枚举已加载机型实际注册的变量
• PMDG 777 和 737 NG3 原生 SDK 支持——通过 PMDG SDK Client Data Areas 直接访问所有机型数据字段和控制事件，还能读取包含颜色和格式的 CDU 屏幕
• 触发事件——切换开关、设置自动驾驶模式、控制灯光、触发自定义 MobiFlight 事件
• 执行 RPN 计算器代码——直接在模拟器中运行任意逆波兰表示法代码
• 搜索和发现变量——可搜索 SimVar、事件和机型专属 L-var 目录，其中包含易读的名称和有效值
• 设施查询——按距离排列附近机场；还可根据 ICAO 标识符查询特定机场、航路点、NDB 或 VOR 的详细信息，数据直接来自 SimConnect 的设施订阅
• 飞行和场景工具——加载和保存 .FLT 飞行，加载 .PLN 飞行计划，并生成 AI 飞机或物体，便于编写测试场景脚本，无需手动设置
• 内嵌文档——以 MCP 资源的形式提供 SimConnect 参考文档，支持离线使用
• 机型专属目录——预先构建的变量数据库，包含面板分组、显示名称和值描述。内置 1,607 个 PMDG 777 变量（777-200LR/200F/300ER/F）和 1,861 个 PMDG 737 NG3 变量（-600/700/800/900，含 BBJ/BDSF/BCF）。
• HubHop 集成——可直接通过 MCP 工具搜索 MobiFlight HubHop 社区预设数据库，也可使用内置客户端为任何受支持的机型生成和扩展 L-var 目录

先决条件

• Microsoft Flight Simulator（MSFS 2020 或 2024），并在同一台机器上运行
• uv——提供 uvx，可为你获取服务及其 Python 运行时
• MobiFlight WASM Module（可选，用于支持 L-var）——安装到 MSFS Community 文件夹中。从 MobiFlight 下载

安装

已发布到 PyPI，名称为 simconnect-mcp， 并已列入 MCP Registry，名称为 io.github.robin24/simconnect-mcp。

安装好 uv 后，无需单独安装——uvx 会按需 获取并运行服务：

uvx simconnect-mcp

这样会通过 stdio 启动服务，MCP 客户端会为你完成此操作。只有在检查服务能否 启动时才需要手动运行；按 Ctrl+C 停止。

若要固定版本，请使用 uvx [email protected]。

从源代码安装（用于开发）

git clone https://github.com/robin24/simconnect-mcp.git
cd simconnect-mcp

# Creates the virtual environment and installs the dev group too
uv sync

配置为 MCP 服务

Claude Code

通过命令行：

claude mcp add --transport stdio simconnect -- uvx simconnect-mcp

也可将其设为所有项目均可使用：

claude mcp add --transport stdio --scope user simconnect -- uvx simconnect-mcp

通过 JSON（~/.claude/settings.json 或项目级 .claude/settings.json）：

{
  "mcpServers": {
    "simconnect": {
      "command": "uvx",
      "args": ["simconnect-mcp"]
    }
  }
}

OpenAI Codex CLI

通过命令行：

codex mcp add simconnect -- uvx simconnect-mcp

通过 JSON：

{
  "mcpServers": {
    "simconnect": {
      "command": "uvx",
      "args": ["simconnect-mcp"]
    }
  }
}

Gemini CLI

通过命令行：

gemini mcp add --transport stdio simconnect -- uvx simconnect-mcp

通过 JSON（~/.gemini/settings.json）：

{
  "mcpServers": {
    "simconnect": {
      "command": "uvx",
      "args": ["simconnect-mcp"]
    }
  }
}

MCP 检查器（交互式测试）

uv run mcp dev src/simconnect_mcp/server.py

注意： 若要运行本地检出版本，而不是已发布的软件包，请将 uvx simconnect-mcp 替换为 uv run --directory /path/to/simconnect-mcp simconnect-mcp， 并使用克隆仓库的绝对路径。

工具（32）

每个工具都以 msfs_ 为前缀，带有明确的 readOnlyHint/destructiveHint 注解，并返回类型化结果或结构化错误，绝不会伪造成功。下表由运行中的服务生成（名称、类型和标题均直接取自各工具的 ToolAnnotations）；描述是工具自身文档字符串中的单行摘要：

uv run python -c "
import asyncio
from simconnect_mcp.server import mcp
async def m():
    for t in sorted(await mcp.list_tools(), key=lambda x: x.name):
        kind = 'read' if t.annotations.readOnlyHint else 'write'
        print(f'| \`{t.name}\` | {kind} | {t.annotations.title} |')
asyncio.run(m())"

连接（3）

工具	类型	描述
msfs_connect	写入	建立与 MSFS 的 SimConnect 连接
msfs_disconnect	写入	关闭与 MSFS 的 SimConnect 连接
msfs_get_connection_status	读取	检查连接状态，以及模拟器是否正在运行或已暂停

SimVar 操作（6）

工具	类型	描述
msfs_get_simvar	读取	按名称读取 SimVar 值，并使用指定单位
msfs_set_simvar	写入	写入可设置的 SimVar 值；若写入被拒绝，会如实报告失败，而不会报告成功
msfs_get_simvars_bulk	读取	一次调用读取多个 SimVar；某个条目失败不会中止其余操作
msfs_search_simvars	读取	按关键词搜索 SimVar 目录
msfs_list_simvar_categories	读取	列出所有 SimVar 类别及其变量数量
msfs_watch_simvar	读取	随时间采样 SimVar，并返回用于调试的时间序列

单位： msfs_get_simvar（以及 msfs_set_simvar）接受可选的 unit 参数，并始终在结果中报告实际使用的单位。省略 unit 时，随附的 SimVar 目录会为该变量提供合理的默认值；对于目录中未收录的变量，默认值为 "number"。

事件操作（3）

工具	类型	描述
msfs_trigger_event	写入	触发 SimConnect 事件，可选传入参数
msfs_search_events	读取	按关键词搜索 SimConnect 事件，可选按类别筛选
msfs_trigger_custom_event	写入	通过 MobiFlight WASM 模块将自定义事件作为按键事件触发

L-Var 操作（6）

工具	类型	描述
msfs_get_lvar	读取	从当前飞机读取 L-var（局部变量）值
msfs_set_lvar	写入	为当前飞机上的 L-var 写入值
msfs_list_lvars	读取	列举当前加载的飞机已注册的 L-var
msfs_execute_calculator_code	写入	在模拟器中执行 RPN 计算器代码
msfs_search_lvars	读取	按关键词搜索随附目录中的已知飞机 L-var
msfs_browse_lvar_catalog	读取	浏览飞机 L-var 目录：列出目录、某个目录中的面板，或某个面板上的变量

msfs_list_lvars 会请求 MobiFlight WASM 模块实时列举飞机实际注册的变量，但该模块最多只返回 1000 个名称，截断时仍会报告列表完整。繁忙的插件配置（如 GSX）可能会挤掉飞机自身的变量，使其完全无法出现在响应中；请留意 truncated: true。应将目录和实时列表视为起点，而非保证完整的清单——msfs_get_lvar 可以读取你提供的任何名称，无论该名称是否出现在其中任何一份列表中。

飞机状态（1）

工具	类型	描述
msfs_get_aircraft_snapshot	读取	读取当前飞机状态快照（一次调用获取位置、速度、姿态和关键系统信息）

设施（2）

工具	类型	描述
msfs_get_nearby_airports	读取	列出某个点附近的机场，按距离从近到远排序
msfs_get_facility_info	读取	根据 ICAO 标识符查询一个机场、航路点、NDB 或 VOR

机场覆盖全球（SimConnect 会返回完整的 85,249 个机场列表，并在首次收集后缓存）。航路点、NDB 和 VOR 的范围仅限飞机当前位置，因此每次调用时都会重新收集，而不会缓存——如果飞机重新定位或开始飞行后仍使用缓存的无线电导航设备列表，查询结果就会对应飞机的先前位置。

实用工具（2）

工具	类型	描述
msfs_send_sim_text	写入	在模拟器中显示文本叠加消息（用于调试反馈）
msfs_set_aircraft_position	写入	重新定位飞机（用于设置测试场景）

PMDG 777 / 737 NG3（3）

工具	类型	描述
msfs_get_pmdg_var	读取	按名称读取 PMDG 飞机数据字段——开关、MCP 值、燃油量、FMC 数据（777 或 737 NG3）
msfs_get_pmdg_cdu	读取	将 PMDG CDU 屏幕读取为文本行，并提供每个单元格的颜色和格式信息
msfs_send_pmdg_event	写入	发送 PMDG 控制事件——切换开关、按下按钮、设置选择器（777 或 737 NG3）

这些工具使用 PMDG SDK Client Data Areas 直接访问飞机状态的二进制数据，绕过 MobiFlight L-var 桥接。系统会根据已加载的飞机自动检测相应 SDK（777 或 737 NG3），也可以通过 variant 参数指定。需要在飞机的 options.ini（777_Options.ini 或 737NG3_Options.ini）中设置 EnableDataBroadcast=1 和 EnableCDUBroadcast.N=1。777 有三个 CDU（Capt/Center/F-O）；737 NG3 有两个（Capt/F-O）。详情请参阅 PMDG 777 SDK 参考 和 PMDG 737 NG3 SDK 参考。

HubHop（2）

工具	类型	描述
msfs_search_hubhop	读取	搜索 MobiFlight HubHop 社区预设数据库
msfs_list_hubhop_aircraft	读取	列出 HubHop 提供预设的飞机

与其他所有工具不同，这两个工具访问的是 HubHop 的 HTTP API，而非模拟器，因此即使 MSFS 已关闭也能使用。首次调用时会下载并缓存完整预设数据库（约 17 MB）；同一服务进程中的后续调用会从内存缓存读取。两个工具共用此缓存，缓存会每 6 小时自动重新获取一次。任一工具都可通过 refresh=true 强制立即重新获取。

飞行与场景（4）

工具	类型	描述
msfs_load_flight	写入	加载已保存的飞行，替换当前飞行
msfs_save_flight	写入	将当前飞行保存到 .FLT 文件 — 除非显式传入 overwrite=true，否则不会覆盖现有文件
msfs_load_flight_plan	写入	将 .PLN 飞行计划加载到飞机的 GPS/FMS 中，替换当前启用的计划
msfs_create_ai_object	写入	在指定位置生成 AI 飞机或对象 — 报告 SimConnect 是否接受了请求；但这不代表对象确实存在（MSFS 会静默忽略标题不匹配的请求）

这些工具封装了底层 SimConnect 飞行／场景文件操作，便于编写测试设置脚本（例如“加载此进近程序”“保存当前状态”“在附近生成交通”），而不是在模拟器自身的 UI 中手动操作。msfs_create_ai_object 已通过 tests/live/test_live_flight.py 完成端到端实机验证：对象已生成、确认能够响应定向 SimVar 请求，然后再次移除。msfs_save_flight 也已完成实机验证，包括 CLAUDE.md 的“已知模拟器行为”中记录的保存后数秒 SimConnect 卡顿；在 2026-08-29 精简实机测试套件时，其自身的实机测试已退役，因为相关发现已记录在该文档中，剩余的覆盖内容（覆盖保护逻辑）是纯 Python 逻辑，tests/test_flight.py 中的模拟测试已涵盖。按设计，msfs_load_flight 和 msfs_load_flight_plan 仅使用模拟测试 — 原因见 tests/live/test_live_flight.py 的模块文档字符串。请参阅下文的运行实机测试。

变量目录

服务内置了全面的变量目录，用于搜索和发现，让 AI Agent 无需猜测即可找到合适的变量名称。

SimVar 目录（1,080+ 个变量）

内置 SimVar 目录涵盖了 25 个类别中所有有文档记录的 MSFS 模拟变量：

类别	变量数	类别	变量数
飞机发动机	112	飞机航电设备	122
飞机燃油	48	杂项	162
飞机操纵装置	50	起落架	54
自动驾驶仪	39	飞行仪表	45
飞机灯光	25	飞机位置和速度	46
摄像机	34	无线电导航	66
服务	42	飞机电气系统	47
飞行模型	11	飞机系统	24
环境	14	以及更多...

该目录的数据源包括 SimConnect Python 包和官方 MSFS SDK 文档，确保覆盖摄像机控制、地面服务、断路器、GPS/NAV/COM 无线电以及飞行模型变量等内容。

Aircraft L-Var 目录

L-var 目录为特定飞机插件提供可搜索、易读的数据库。服务端会通过三个步骤选择目录，并在结果的 message 中告知是哪一步匹配成功——这三种方式的可信度差异很大：

1. 探测 PMDG SDK 客户端数据区域。 这是权威方式，且不依赖飞机如何标识自身。这一步最重要，因为 PMDG 飞机不会将自身标识为 PMDG：一架真正的 PMDG 737-800 会将 TITLE 报告为 737-800 PAX SSW TC，其中完全没有厂商名称。仅匹配标题对它们从来行不通。
2. 将 title_pattern 与 TITLE/ATC_MODEL 匹配。 这是后备方式，也是你自行提供的目录唯一可用的机制。
3. 搜索所有目录并明确说明。 此时结果会带有 Catalog 列，让你知道每一行属于哪架飞机，而不是把另一架飞机的变量当成自己的来读取。

传入 catalog=<key> 可限定搜索范围；也可以不带参数调用 msfs_browse_lvar_catalog，列出可用的键。

显而易见的捷径——将 title_pattern 扩大为 737——是我们刻意没有采用的做法。这样会同样匹配 iFly 737 MAX 和 Asobo 自带的 737，并向驾驶非 PMDG 飞机的用户提供 PMDG 目录。坦诚地说“未检测到目录”，胜过自信地给出错误结果。

内置目录：

Aircraft	Variables	Panels	Source
PMDG 777（所有变体）	1,607	28	SDK 头文件解析 + HubHop
PMDG 737 NG3（-600/700/800/900/BBJ/BDSF/BCF）	1,861	27	SDK 头文件解析 + HubHop

每个变量都包含显示名称、类别、可写标志，以及（如适用）有效值映射。

未随附 Fenix 目录——之前的 fenix_a320.json（1,433 个普通 L-vars）已被移除，改用 HubHop 自带的、更全面且由社区维护的 FenixSim 覆盖数据（2,273 个预设；Fenix 每次发布更新时都会同步更新，而随附的快照只会逐渐过时）。你可以通过 msfs_search_hubhop(vendor="FenixSim") 实时搜索，也可以使用下方的 HubHop 客户端重新生成本地目录文件，并将其放入 src/simconnect_mcp/data/——启动时会自动发现其中的所有 *.json，因此无需修改代码即可立即使用。

添加新的飞机目录

通过内置的 HubHop 客户端添加新飞机目录是最快的方式：

# See what's available
python -m simconnect_mcp.data.hubhop --list-vendors

# Generate a catalog (example: FlyByWire A32NX)
python -m simconnect_mcp.data.hubhop \
    --vendor "FlyByWire Simulations" \
    --aircraft "A320neo" \
    --aircraft-name "FlyByWire A32NX" \
    --title-pattern "A32NX" \
    -o fbw_a32nx.json

或者更新现有目录：

python -m simconnect_mcp.data.hubhop --vendor FenixSim --merge fenix_a320.json

你也可以使用 Python API：

from simconnect_mcp.data.hubhop import HubHopClient

client = HubHopClient()
presets = client.fetch_presets(vendor="FlyByWire Simulations", aircraft="A320neo")
catalog = client.build_catalog(presets, aircraft="FlyByWire A32NX", title_pattern="A32NX")
client.save_catalog(catalog, "fbw_a32nx.json")

或者手动创建目录，将 JSON 文件放入 src/simconnect_mcp/data/。启动时会自动发现所有 *.json 文件。完整指南、JSON schema 和最佳实践请参阅 docs/extending-catalogs.md。

资源

URI	Type	Content
simconnect://docs/overview	text/markdown	SimConnect 架构和关键概念
simconnect://docs/simvars/{category}	text/markdown	按类别排列的 SimVar 参考
simconnect://docs/events/{category}	text/markdown	按类别排列的事件参考
simconnect://docs/rpn	text/markdown	RPN 计算器语法指南
simconnect://docs/lvars	text/markdown	插件开发中的 L-var 用法
simconnect://docs/best-practices	text/markdown	常见陷阱和性能提示
simconnect://docs/pmdg/{variant}	text/markdown	PMDG SDK 参考；variant 可以是 777 或 737（接受以 B 开头的形式，不区分大小写）
simconnect://state/connection	application/json	实时连接状态
simconnect://state/aircraft	application/json	当前飞机的标题、类型和位置

提示词

提示词	用途
debug_simvar	分步指导如何调试行为异常的 SimVar
analyze_aircraft_vars	列举并分类当前飞机上的所有 L 变量
create_addon_boilerplate	按类型生成插件起始代码
rpn_helper	将自然语言转换为 RPN 计算器代码
simconnect_code_review	检查 SimConnect 代码中的常见问题

项目结构

src/simconnect_mcp/
├── server.py              # FastMCP instance, lifespan, tool registration
├── connection.py          # SimConnectManager singleton + native set_lvar
├── dispatch.py            # SimConnectDispatcher — owns the SimConnect dispatch loop
├── simvar_access.py       # SimVarAccessor — generic SimVar reads/writes via data definitions
├── facilities.py          # Facility (*_LIST) message parsing and accumulation
├── pmdg.py                # PMDG 777 SDK structs, CDU rendering, data manager
├── pmdg_ng3.py            # PMDG 737 NG3 SDK structs, CDU rendering, data manager
├── tools/
│   ├── __init__.py        # @handle_simconnect_errors, @require_connection decorators
│   ├── connection_tools.py # connect_to_sim, disconnect_from_sim, get_connection_status
│   ├── simvars.py         # SimVar CRUD via SimVarAccessor (1,080+ vars in the catalog)
│   ├── events.py          # Event trigger/search + built-in catalog
│   ├── lvars.py           # L-var read/write/search/enumerate/browse catalogs/calculator code
│   ├── pmdg.py            # PMDG tools — auto-dispatch to 777 or 737 NG3
│   ├── aircraft.py        # get_aircraft_snapshot — combined state snapshot
│   ├── facilities.py      # Airport/navaid lookup on top of facilities.py
│   ├── flight.py          # load/save flight, load flight plan, spawn AI object
│   ├── hubhop.py          # HubHop preset search, exposed as MCP tools
│   ├── utilities.py       # send_sim_text, set_aircraft_position
│   ├── models.py          # Shared Pydantic result/error models
│   └── formatting.py      # Pagination and markdown-table helpers
├── data/
│   ├── catalog.py         # L-var catalog loader and search engine
│   ├── simvar_catalog.py  # SimVar catalog loader, unit resolution, string-var detection
│   ├── hubhop.py          # MobiFlight HubHop API client (CLI + library), in-memory cache
│   ├── pmdg_777.json      # PMDG 777 catalog (1,607 vars, 28 panels)
│   ├── pmdg_737.json      # PMDG 737 NG3 catalog (1,861 vars, 27 panels)
│   └── simvars_catalog.json  # Built-in SimVar catalog (1,080+ vars, 25 categories)
├── vendor/                # Byte-faithful to upstream except two documented local changes
│   ├── simconnect_mobiflight.py          # unmodified
│   └── mobiflight_variable_requests.py   # log-level demotion + response-channel routing
└── docs/                  # Embedded documentation, served as MCP resources
    ├── overview.md, simvars.md, events.md, rpn.md, lvars.md, best_practices.md
    ├── pmdg_777.md        # PMDG 777 SDK reference
    └── pmdg_737.md        # PMDG 737 NG3 SDK reference

PMDG 目录由 scripts/parse_pmdg_sdk.py 根据 SDK 头文件重新生成——该脚本会自动检测结构体名称和 CDU 数量，因此同一脚本可处理 777 和 737 NG3。

开发

# Run the mocked test suite (no MSFS required; live tests are deselected by default)
uv run pytest

# Run tests with verbose output
uv run pytest -v

# Run only specific test files
uv run pytest tests/test_hubhop.py    # HubHop client tests
uv run pytest tests/test_simvars.py   # SimVar catalog tests

# Lint
uv run ruff check src/ tests/

测试会模拟 SimConnect，因此上述测试套件无需 MSFS 即可运行。tests/conftest.py 提供了一个模拟 SimConnect，并包含符合实际情况的 SimVar 值。

运行实时测试

tests/live/ 下的第二个测试套件会测试真实的 SimConnect DLL，并标记为 @pytest.mark.live。pyproject.toml 默认会将其排除（addopts = "-m 'not live'"），因此在没有 MSFS 的机器上（包括 CI）绝不会运行。

该测试套件刻意保持精简，今后也会如此：只有当自洽的模拟无论代码是否正确都可能自圆其说时，测试才应放在这里。例如，写入并读回单个 L 变量名称的往返测试无法证明编码正确，因为经过篡改的数据项名称会导致写入和读回都对应同一个错误变量（请参见 tests/live/test_live_lvars.py 中的 test_two_distinct_lvars_do_not_collide）。经过这项筛选后留下的，是模拟只能假定、无法验证的真实 DLL 或 DLL 邻近行为：与物理常量进行单位换算、对本项目曾发现第三方绑定错误的结构体进行线路解码、哪些真实 SimVar／事件接受写入，哪些会拒绝或静默忽略写入、未文档化的 MobiFlight/WASM 协议特性，以及真实 PMDG 的二进制客户端数据区是否会以其结构体解码所预期的方式响应探测。

如果可以将实时测试发现固化为已提交的测试夹具并离线重放，则优先采用这种方式，而非实时测试：tests/fixtures/facilities/ 保存了一次性捕获的真实 SimConnect 线路字节；每次运行时，都会由模拟的 tests/test_facilities_parsing.py 重放，无需模拟器且不会产生不稳定结果——这样可以确定性地固定同一发现，而不依赖当天恰好加载的飞机。

uv run pytest -m live

需要运行 MSFS 并加载飞机；如果测试连接失败，则会跳过而非判定失败（请参见 tests/live/conftest.py 中的 live_manager 夹具）。tests/live/test_live_pmdg.py 中的测试需要加载真实的 PMDG 737/777；如果已加载的飞机看起来不是这两款之一，则会跳过而非判定失败（请参见 tests/live/conftest.py 中的门控逻辑）。

许可证

版权所有 (C) 2025-2026 Robin Kipp

本程序是自由软件：您可以根据自由软件基金会发布的 GNU Affero 通用公共许可证条款重新分发和／或修改本程序；许可证版本为第 3 版，或者（由您选择）任何更高版本。完整文本请见 LICENSE.txt。

本项目采用 AGPL-3.0 许可证，因为它依赖 Python-SimConnect，该项目本身采用 AGPL-3.0 许可证。

src/simconnect_mcp/vendor/ 中随附的 MobiFlight 桥接程序是独立作品，由 Koseng 采用 MIT 许可证授权——请参见 src/simconnect_mcp/vendor/MOBIFLIGHT_LICENSE。