内容
htastic-mCI](https://github.com/meshtastic/meshtastic-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/meshtastic/meshtastic-mcp/actions/workflows/ci.yml)
[](https/project/meshtastic-mcp/)
[](https/project/mes-mcp/)
[
uff](https.shields.io/=https://rawastral-sh/main/assets/badge/vhttps://github.com/astral-sh/ru一个用于AI工具园，用于**发现、观察和测试** Meshtastic设备和与其应用程序。一个 [MCP://modelcontextprotocol.io附带一套捆代理技能，用于闭环设备 ↔ 应用端到。
> 从Mes固件仓库的`-server/`中提取和解耦，以便它可以和分发。固成为一个可选存在固件checkout时才会启用。
## 快速60秒）
htastic设备，然后```bash
uvhtastic-mcp doctor # 检查可用性
```
Code（或任何注册了`meshtastic`的MCP客户端）中：
```
list_devices() 查找设备端口_info(port="/dev/cbmodem101") → 固件、区域数
list_nodes(port/cu.usbmodem → 网状对等节点
send_textdev/cu.usem101", text="")
packets_windowdev/cu.usbmodem101", start="-30s") → 确认包
```
不需要固件checkout。核心工具适用于任何串行或TCP设备。
## 安装
```bash
# 安装CLI + MCP服务器（推荐使用uv，也支持pipx）
uv tool install 'meshtastic-mcp[ui]' # 包括摄像头/OCR支持
# 或不带UI额外功能：
uv tool install meshtastic-mcp
# 其他额外功能：[ FleetSuite基准测试 [sdr] RF性 · [test] pytest测试框架
# 从本地checkout安装（开发中）：
uv tool install --editable '/path/to/meshtastic-mcp[ui]'
# 一步到位：注册服务器到MCP客户端 + 安装捆绑技能
meshtastic-mcp install # Claude范围；--client cursor|windsurf|cl
meshtcp install --local # 注册当前解释器（可编辑/开发安装htastic-mcp install --print # 仅代码段（不编辑meshtastic uninstall # 删除注册（--purge-skills技能）
# 或以下操作：
clcp add meshtastic user -- meshtcp # 注册到Claude Code
meshtastic-mcp skills install agents/skills/（设备操作、端到端测试、组织知识）
mes-mcp skills uninstall 删除它们
```
`install修改客户端的`Servers` JSON保留其他条目），根据`--clientclaude-code / cl / cursor / windsurf）和`--scope`项目）选择正确的配置文件路径，也可以传递`--`。添加环境变量--env KEY=VALUE`。重启MCP客户端以应用更改。
### 源（可选功能）
设置环境变量指向本地checkout以激活固件构建、Apple功能。`provision`子命令会自动克隆
```bash
meshtastic-mcp provision # 克隆固件 apple，打印
source ~/.local/sharehtastic-mcpenv
# 然后配置文件中：
export MES_FIRMWARE_ROOTmeshtastic/fexport MESHTASTIC_ANDROID~/meshtastic/android
export MESHTPLE_ROOT=~/meshtastic/apple
# 将以下内容添加到MCP客户端配置文件服务器进程获取：
env": { "MESHTASTIC_FIRMWARE "/path/to/firmware", ... } }
```
esptool** — 如果已安装PlatformIO，则会自动IO环境中发现esptool并自动无需手动设置。
```meshtastic-m # 验证设置生效
```
## 功能**可移植的核心**始终适用于任何连接的串行或`tcpport`），无需固件checkout。可选功能在满足先决条件时激活：
| 功能 | 先决条件 | 添加 |
|---|---|---|
| **核心** | — | 发现、串行+TCP传输、`device_info`/`list_nodes`/管理/`send_text`/重启、记录器 + 日志//数据包查询、**重（模拟TCP设备 +状网络 + ）、输入事件、uhubctl、`espt/`nrfutil`/`picotool` |
固件** |ASTIC_FIRMWARE_ROOT` + PlatformIO `pio 构建/刷写/OTA/板子枚举/用户首选项 |
| **安卓 `android` CLI +` | 安卓模拟器 + 原生节点编排，用于无硬件端到端测试 |
| **苹果 `xcrun `idb`) | iOS模拟器 / macOS应用编无硬件端到| **本地 | 可达的ama或OpenAI`llama-server`启动一个的`llama`二进制文件）卸载到本地 总结/分类记录窗口、端到端故障初步离线**视觉预言**；参见 [docs.md](-models.md) |
|R** | `[sdr]`额外 + `lsdr` + RTL-SDR加密狗 |规性预言rf_scan`占用检查rf_confirm_tx`，无需第二个无线| **SDK-CLI** *(实验性)* SDK无头CLI | 通过JVM CLI的替代后端；参见 [-cli-bridge.md/sdk-cli-bridge.md) |
活动集在启动时记录（`meshtastic-mcp capabilities active:）。
除了工具之外，服务器还公开MCP **资源**（`meshtastic://doctor`htastic://capabilities`和模板化的`mes://e2e/{loop}`用于捆端到端测试）和**提示**（`_e2e_failurebringup_device`bound_loop`）。_docs_search`/`_fetch`工具根据官方回答Android/Compose问题。
### 源代码仓库 — 两种模式
构建工具（`build_meshtasticd.sh`、`build_android_apk.sh`、`build_apple.sh`）在两种模式下工作：
**使用现有checkout进行开发** — 将环境变量指向本地树：
```bash
export MESHTASTIC_FIRMWARE_ROOT=~/firmware
export MESHTASTIC_ANDROID_ROOT=~/Meshtastic-Android MESHTASTIC_APPLE_ROOT=~/Meshtastic-Apple
```
**便携/** — 一次克隆所有内容：
meshtastic provision # 克仓库，写入
source ~/.local/sharehtastic-m/.env
```
`会保留已设置的任何环境变量（跳仓库），并为克隆的仓库编写可源`.env`文件。运行`doctor`后，确认所有二进制依赖项。
### `doctor`探测环境
在开始端到端工作之前运行（也可以作为`CP工具公开代理进行自我配置```bash
mes-mcp doctor 每个依赖项的状态 + 确切的、平台感知的安装命令
meshtastic-mcp doctor -- 机器可`fix_commands[]`已准备好运行
二进制文件（`、`adb`、`un`、`idanion`、`fb`、`ffmpeg`、`ctl`、**和**源根目录（`MESHTASTIC_FIRMWARE_ROOT`、`MESHTASTIC_ROOT`、`MESPLE_ROOT`），报告`ok`/`missing`/`degraded`以及确切的修复命令 包括不明显的命令（例如`idb_companion`位于`facebook`tap，`b`需要Python3.12）。
### 构建脚本
本 | 构建关键标志 |
| `scripts/buildasticd.sh`生`mesht守护进程 | native\|native-m， `--ref`firmware-dir` / `MESHTASTIC_FIRMWARE_ROOT` |
|/build_android_ap` | Meshtastic-Android APK | `--， `--variant`， `--source-dir` / `MESHTASTIC_ANDROID_ROOT` |
| `scripts/build_apple.sh` | Meshtastic iOS模拟器`.app` | `--ref`， `--sim`， `--source-dir` / `MESHTASTIC_APPLE_ROOT` |
所有脚本在没有提供源目录的情况下克代码，接受ref`以固定/tag/branch，
并机器可读的`<component>-sha=<行用于CI溯## 无硬件端测试（模拟器）
Portduino `asticd`作为TCP守护`:4403`，并通过UDP多`224.0.69:440与**无硬件**的网交互。安卓模拟TCP连接到`10.0.2.2>`作为其DUT无线电；M连接到其他原生节点者。每个端循环 — 入站/出站消息、节点同步、配置写回、弹性 — 都在软件中运行，可以在Linux运行进行CI测试。参见`src/mesht/emulator/native_node.py`和捆绑的`meshtastic-e2e`技能。
## — 模拟的Meshtastic设备记录器的逆向）
记录器*订阅状网络并写入数据包，而**重放** *提供*作为TCP上的假无线电。一个应用程序（或.0.2.2:<port>`上的AVD）连接到监听端口的配置握手并接收一个按需的数据包流 —得像一个坐在网状网络中的无线电/UI开发和需硬件和完全可控、可重复的网状网络。
```pythonplay_start(source="mesh # 生成网络（无文件）
replay_startcapture.db", speed) # SQLite捕获保真有效）
replay_startevent.db", # 按OTA解密拆分
": "Primary", "psk": "AQ==", "primary {"nameSecret", "psbase64-key>"},
{"nameUnknown", "catch_all": True}])
replay_start(source="meshcon", fuzz="adversary") # 用坏演员编织
replay_start(source="capture.db", announce_interval=30) # 应用内“重放时钟”进度
replay_inject(sid, "waypoint", {"lat":37,"lon":-122,"geofence_radius,"notify_on_enter":True})
replay_status(); replay_stop()
```
-** (`reapture.py`)：SQLite捕获 (`*.db`/`，燃烧人 / DEF CON / 网)，记录器的自己的`packets.jsonl或内存中的综合网状网络。
-通道捕获**：`channels`列表 + PSK，可选的显式OTA选的`catch桶）以将路由到真实通道OTA通道哈希密钥，以便连接的应用并实时解密加密通道集是由调用者提供的数据 —事件捕获，提供事件名称 + PSK事件特定的内容被硬编码。
- **综合网状网络** (`replay/sim.py`)，无PII的*网状会议*生成器 — 可调节点计数（默认800，扩展千）/通道，一个日活动，每个portnum/风味（包括R）。其默认分布角色混合，遥测值范围，，跳限制，文本速率，**节点存在/变化** — 一个持久的核心 + 暂时的者，它重现真实的活动偏差 —
短消息长度，以及加密/量的份额）由真实~1800节点汇总统计信息（燃烧人 + DEF CON — 仅比例；每个身份，位置都是生成的。`sim.fit_profile(capture任何捕获中导出这样的配置文件。
- **实时 (`replay`)：将精确的数据包推送到正在中，以按应用程序功能 — 围栏的航点，节点位置交叉，文本，节点信息，或`raw`。构建replay/build）设置原型字段，捆绑库在其之前是原始电线追加；`fuzz=True`注入故意损坏的数据包（共享模糊器的发射路径）。`capture.from_events([…])`将脚本场景转换为可重放的捕获。（针对Android航点-地理围栏PR进行端到端验证。）
- **面向应用色**：连接的节点放置在捕获位置（合理的地图 + 距离）；ounce_interval`添加一个“重放时钟发布启动 + 实时ETA/进度到忙的通道；_preset`ware_edition广告LoRa预应用的事件横幅（例如`DEF，`HAMVENT）；`replay_status`返回`connect`主机：端口提示；发送超时保持应用不会挂起会话。
- **模糊器** (`replay/fuzz.py`, `replay_start(fuzz=…)`, `replay_fets`)流对解码 UI鲁棒性进行测试。*协议损坏/垃圾的有效载portnum↔body不匹配，无效UTF-8文本，不可能遥测，传送位置，异常，丢弃/重复）和*坏演员活动*（邪恶双胞胎伪造水，GPS欺骗，伪造ACK氓ADMIN重启/工厂重置，恶点）。种子化以使崩溃重活动表面在``下`replay_status`。预`light`parser`，`adversary`，os`.
## 技能
包含在轮子中（`meshtastic skills install`将它们复制到您的技能目录中）：
-htastic-device- — 通过M界面进行设备发现/配置/观察/恢复/刷写端到端）。
- **`meshtastic-e2e 跨平面（设备 + 应用）测试循环引用，验证助手（_e2e.py基于旅UI**（`ourneys/`），分类和视觉预言的备用。
- **`meshtastic-org-knowledge`** — 回答跨越Meshtastic GitHub组织的疑问：哪个项目执行X，Y的状态，Z在哪里记录，近期有什么变化。
## FleetSuite — 设备基准测试的Web控制面板
用于运行多板硬件基准测试的本地Web实时设备（发现 +件/硬件），构建队列 + 刷写，一个逐步梯（重启断电循环 →加载程序 → 重新刷写），每个流用于屏幕断层测试运行器，串行监视器和可选的Dat/指标发送bash
uv toolmeshtastic-mcp[web]'
mescp-web # http://127.0.1:8765上的桌面meshtastic-m --browser #服务（无行打开默认绑定到`127.0.0.1`。破坏性重新刷写重置）需要显。在FleetSuite拥有基准测试的端口（监 + 丰富 暂停它或自己的控件，而不是将第二个工具指向同一个端口测试运行器已经暂停监视器整个运行时间。从源代码检出中./scripts/fle.sh`一键引导所有内容（虚拟环境 + npm + SPA`./scripts/web-dev.sh`运行后端开发服务器，启用HMR。指向`MESHTASTIC_FIRMWARE_ROOT`到固件检出以启用构建、刷新恢复和精确的每个板子环境解析 — 没有它，Fleet会发现，丰富和驱动设备。
件测试套件
`tests/`是一个分层pytest套件（`unit`，`mesh`，`telemetry`，`monitor`，`recovery`，`ui`，`，`admin`，`provisioning`unit`在无硬件的情况下运行；硬件层级针对具有每个板的USB集线器基准测试（参考基准测试：T-Echo，Heltec T114，RAK463ESP32-S3 — 参见`bench.py`和[tests/README.md](tests/README.md)）。通过-tests.sh`，`meshtastic-mcp-test-tui`终端UISuite的测试运行器驱动它设置您自己的基准测试**（子，任意集线器）：/bench-setup.md](docs/bench-setup.md).
## 许可证
仅限GPL-3.0。
