MeshCore MCP服务器

MCP（模型上下文协议）服务器，提供通过HTTP与MeshCore伴随无线电节点交互的工具。这使得人工智能助手和基于网络的工具能够控制网状网络设备并与之通信。

示例用法

以下是使用MeshCore MCP服务器与Claude的真实对话：

👤 用户： 你连接到MeshCore了吗？

🤖 克劳德： 是的，我已连接到MeshCore。我可以看到设备信息显示 Heltec V3 运行固件版本的设备 8（v1.10.0-9405e8b） 建于2025年11月13日。该设备最多支持350个触点和40个通道。

👤 用户： 我有留言吗？

🤖 克劳德： 不，你没有任何消息。您的消息缓冲区当前为空。

👤 用户： 有人发了一条信息。你能再查一下吗？

🤖 克劳德： 你说得对！您现在确实有消息。有 1条消息 在您的缓冲区中：

消息详细信息：

发件人： 未知（公钥： 2369759a4926)
时间： 2025年11月22日13:46:24
留言： “你好，GitHub！”

它似乎来自一个未知的联系人，但您可以看到他们的公钥标识符。

👤 用户： 回复“Hello World！”

🤖 克劳德： 我已成功发送您的回复！消息 “你好，世界！” 已发送给联系人 2369759a4926系统确认消息已成功发送。

特性

核心工具：

meshcore_connect -通过串行、BLE或TCP连接到设备
meshcore_disconnect -与设备彻底断开连接
meshcore_send_message -向联系人或渠道发送消息
meshcore_send_advert -发送广告以宣布设备存在
meshcore_get_contacts -列出所有联系人
meshcore_get_device_info -查询设备信息
meshcore_get_battery -检查电池状态

时钟管理工具：

meshcore_get_time -获取当前设备时间
meshcore_set_time -将设备时间设置为特定的Unix时间戳
meshcore_sync_clock -将设备时钟与系统时间同步

信息监听工具：

meshcore_start_message_listening -开始接收传入消息
meshcore_stop_message_listening -停止接收消息
meshcore_get_messages -从缓冲区检索接收到的消息
meshcore_clear_messages -清除消息缓冲区

运输：

具有流式传输的HTTP（MCP协议2025-03-26）
浏览器客户端和代理可以访问Web
可配置的主机/端口绑定

Docker快速入门（推荐）

运行MeshCore MCP Server最简单的方法是使用我们的官方Docker镜像：

# Basic usage (port 8000)
docker run -d \
  --name meshcore-mcp \
  -p 8000:8000 \
  ghcr.io/ipnet-mesh/meshcore-mcp:main

# With serial device access (Linux)
docker run -d \
  --name meshcore-mcp \
  -p 8000:8000 \
  --device=/dev/ttyUSB0 \
  ghcr.io/ipnet-mesh/meshcore-mcp:main \
  --serial-port /dev/ttyUSB0 --baud-rate 115200

# With auto-connect and clock sync (recommended)
docker run -d \
  --name meshcore-mcp \
  -p 8000:8000 \
  --device=/dev/ttyUSB0 \
  ghcr.io/ipnet-mesh/meshcore-mcp:main \
  --serial-port /dev/ttyUSB0 --sync-clock-on-startup

# Custom port
docker run -d \
  --name meshcore-mcp \
  -p 3000:8000 \
  ghcr.io/ipnet-mesh/meshcore-mcp:main

可用标签：

main -最新开发版本
latest -最新稳定版本
vX.Y.Z -特定版本标签

Docker编写示例：

version: '3.8'
services:
  meshcore-mcp:
    image: ghcr.io/ipnet-mesh/meshcore-mcp:main
    ports:
      - "8000:8000"
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    command: ["--serial-port", "/dev/ttyUSB0", "--sync-clock-on-startup"]
    restart: unless-stopped

从源安装

先决条件

Python 3.10或更高版本
MeshCore兼容设备（通过串行/BLE/TCP连接）

从源代码安装

# Clone the repository
git clone https://github.com/ipnet-mesh/meshcore-mcp.git
cd meshcore-mcp

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# OR
.venv\Scripts\activate     # Windows

# Install dependencies
pip install -e .

用法

启动HTTP服务器

使用Docker（推荐）： 看上面的部分。

使用Python（本地开发）：

默认值（本地主机：8000）：

python -m meshcore_mcp.server

自定义主机/端口：

python -m meshcore_mcp.server --host 0.0.0.0 --port 3000

自动连接到串行设备（推荐）：

python -m meshcore_mcp.server --serial-port /dev/ttyUSB0 --baud-rate 115200

这将在启动时连接到设备，如果连接失败，则会很快失败。调试模式可以通过以下方式启用 --debug.

具有自动连接和时钟同步功能（建议用于精确的时间戳）：

python -m meshcore_mcp.server --serial-port /dev/ttyUSB0 --sync-clock-on-startup

这将在启动时连接到设备，并自动将设备时钟与系统时间同步，确保消息时间戳准确。

作为已安装的命令：

meshcore-mcp --serial-port /dev/ttyUSB0 --debug

服务器将打印：

Starting MeshCore MCP Server on 0.0.0.0:8000
Server URL: http://0.0.0.0:8000
[STARTUP] Auto-connect enabled for /dev/ttyUSB0
[STARTUP] Server starting, connecting to device...
[STARTUP] Attempting to connect to /dev/ttyUSB0 at 115200 baud...
[STARTUP] Successfully connected to MeshCore device on /dev/ttyUSB0
[STARTUP] Syncing device clock to system time...
[STARTUP] Clock synced successfully to 2025-11-22 14:30:00
[STARTUP] Device connected. Starting message listening...
[STARTUP] Subscribed to contact messages
[STARTUP] Subscribed to channel messages
[STARTUP] Subscribed to advertisements
[STARTUP] Auto message fetching started
[STARTUP] Message listening active with 3 subscriptions
[STARTUP] Server ready.

（时钟同步消息仅在使用时显示 --sync-clock-on-startup)

服务器会自动订阅传入的消息和广告，因此可以立即接收和缓冲消息。

使用克劳德桌面

将此配置添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "meshcore": {
      "url": "http://localhost:8000"
    }
  }
}

对于远程服务器：

{
  "mcpServers": {
    "meshcore": {
      "url": "http://your-server-ip:8000"
    }
  }
}

使用OpenWebUI

OpenWebUI使用 MCPO （MCP到OpenAPI代理）连接到MCP服务器。配置MCPO：

1.创建一个 config.json 文件：

{
  "mcpServers": {
    "meshcore": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

_看 examples/mcpo_config.json 举一个完整的例子。_

对于远程服务器：

{
  "mcpServers": {
    "meshcore": {
      "type": "streamable-http",
      "url": "http://your-server-ip:8000/mcp"
    }
  }
}

2.使用Docker运行MCPO：

# Note: MCPO runs on port 8080 to avoid conflict with the MCP server on 8000
docker run -d \
  --name mcpo \
  -p 8080:8000 \
  -v $(pwd)/config.json:/app/config/config.json \
  ghcr.io/open-webui/mcpo:main

重要提示： MCP服务器在端口8000上运行，而MCPO在端口8080上暴露以避免冲突。根据您的环境需要调整端口。

3.配置OpenWebUI：

在OpenWebUI设置中，将MCPO端点添加为OpenAPI服务器。然后，这些工具将可用于您的AI模型。

另请参见： OpenWebUI MCP文档和

与其他MCP客户端

HTTP服务器与支持流式HTTP传输（MCP协议2025-03-26）的任何MCP客户端兼容。

服务器终结点： http://localhost:8000/mcp

注： MCP端点需要与会话管理进行适当的MCP协议握手。使用MCP兼容的客户端库（如官方MCP SDK）或MCPO等代理与非MCP工具集成。

工具示例

连接到设备

串行连接：

{
  "type": "serial",
  "port": "/dev/ttyUSB0",
  "baud_rate": 115200,
  "debug": true
}

BLE连接：

{
  "type": "ble",
  "address": "12:34:56:78:90:AB",
  "pin": "123456"
}

TCP连接：

{
  "type": "tcp",
  "host": "192.168.1.100",
  "port": "4000",
  "auto_reconnect": true
}

发送消息

{
  "destination": "Alice",
  "text": "Hello from MCP!"
}

发送广告

零跳广告（仅限近邻）：

{
  "flood": false
}

淹没广告（通过中继器进行多跳）：

{
  "flood": true
}

广告向网状网络宣布您的设备存在。使用 flood: false 用于向近邻进行零跳广播，或 flood: true 用于由所有网络中继器重复的多跳广播。

获取联系人

呼叫 meshcore_get_contacts 没有参数来检索您的联系人列表。

查询设备信息

呼叫 meshcore_get_device_info 获取设备名称、版本和配置详细信息。

检查蓄电池

呼叫 meshcore_get_battery 以获取当前电池电量和状态。

管理设备时钟

获取设备时间：

{}

呼叫 meshcore_get_time 从设备中检索当前时间。

将时钟与系统时间同步：

{}

呼叫 meshcore_sync_clock 以使设备时钟与当前系统时间同步。这是确保时间戳准确的最简单方法。

设置具体时间：

{
  "timestamp": 1732276800
}

呼叫 meshcore_set_time 将设备时钟设置为特定的Unix时间戳（自纪元以来的秒数）。

倾听信息

开始收听：

{}

呼叫 meshcore_start_message_listening 开始接收消息。消息存储在缓冲区中（最多1000条消息）。

获取收到的消息：

{
  "limit": 10,
  "message_type": "contact"
}

limit：可选，要检索的最新邮件数
message_type：可选，按“联系人”或“频道”过滤
clear_after_read：可选，设置为 true 阅读后清除消息

停止听：

{}

呼叫 meshcore_stop_message_listening 停止接收新消息（保留缓冲区）。

清除消息缓冲区：

{}

呼叫 meshcore_clear_messages 清空消息缓冲区。

与克劳德的对话示例

You: Connect to my MeshCore device on /dev/ttyUSB0

Claude: I'll connect to your MeshCore device.
[Uses meshcore_connect tool]
Successfully connected to MeshCore device via serial

You: What's my battery level?

Claude: Let me check your battery status.
[Uses meshcore_get_battery tool]
Battery Level: 85%

You: Sync the device clock

Claude: I'll synchronize the device clock with the current system time.
[Uses meshcore_sync_clock tool]
Device clock synchronized successfully!
  System Time: 2025-11-22 14:30:00
  Unix Timestamp: 1732285800

You: Send a message to Bob saying "Meeting at 3pm"

Claude: I'll send that message to Bob.
[Uses meshcore_send_message tool]
Message sent to Bob: "Meeting at 3pm"
Result: MSG_SENT

You: Start listening for messages

Claude: I'll start listening for incoming messages.
[Uses meshcore_start_message_listening tool]
Started listening for messages. Messages will be buffered and can be retrieved with meshcore_get_messages.

You: Check if I have any messages

Claude: Let me check your messages.
[Uses meshcore_get_messages tool]
Messages (2 total):
============================================================

[1] CONTACT MESSAGE
  Time: 2025-11-21T10:30:15
  From: Alice
  Public Key: a1b2c3
  Message: Got it, see you at 3!
------------------------------------------------------------

[2] CHANNEL MESSAGE
  Time: 2025-11-21T10:32:00
  From: Bob
  Public Key: d4e5f6
  Channel: 0
  Message: Weather looks good today
------------------------------------------------------------

“公钥”字段是发件人的地址，在使用meshcore_send_message进行回复时应将其用作目的地。

建筑

服务器使用 FastMCP 随着 可流式HTTP传输 为了提高网络的可访问性。连接状态是全局管理的，所有工具在执行命令之前都会验证连接。

关键部件：

HTTP服务器：具有流式http传输的FastMCP（MCP 2025-03-26）
服务器状态：全球 ServerState 类维护连接实例和消息缓冲区
消息缓冲区：通过自动溢出处理，最多可存储1000条接收到的消息
事件订阅：通过meshcore事件系统进行实时消息处理
工具装饰器：每个工具使用 @mcp.tool() 用于自动注册
错误处理：所有命令都检查EventType。错误响应
连接类型：支持串行、BLE和TCP，并进行适当的验证

为什么是HTTP？

网络可访问：与基于浏览器的客户端和代理兼容
无状态选项：如果需要，可以水平缩放
远程访问：从网络上的任何位置连接
标准协议：使用MCP流式HTTP（最新标准）

发展

构建Docker镜像

# Build locally
docker build -t meshcore-mcp:local .

# Run your local build
docker run -p 8000:8000 meshcore-mcp:local

# With device access
docker run -p 8000:8000 --device=/dev/ttyUSB0 meshcore-mcp:local \
  --serial-port /dev/ttyUSB0

项目结构

meshcore-mcp/
├── src/
│   └── meshcore_mcp/
│       ├── __init__.py
│       └── server.py          # FastMCP HTTP server
├── examples/
│   └── claude_desktop_config.json
├── Dockerfile                  # Docker image definition
├── pyproject.toml
├── README.md
└── LICENSE

运行测试

# Activate virtual environment first
source .venv/bin/activate

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

测试服务器

使用Docker：

docker run -p 8000:8000 ghcr.io/ipnet-mesh/meshcore-mcp:main

使用Python（本地开发）：

# Activate virtual environment first
source .venv/bin/activate

# Start the server
python -m meshcore_mcp.server --port 8000

使用MCP客户端进行测试：

服务器使用MCP Streamable HTTP协议，需要适当的MCP客户端库进行测试。由于会话管理要求，不建议直接进行卷曲测试。

测试时，使用：

克劳德桌面 如上所示的配置
MCPO 公开为OpenAPI（请参阅OpenWebUI部分）
MCP-SDK 您首选语言的客户端库

快速验证服务器是否正在运行：

# This should return an error about missing session ID (which confirms the MCP endpoint is active)
curl -X GET http://localhost:8000/mcp -H "Accept: text/event-stream"

故障排除

连接问题：

验证设备是否已通电且可访问
检查端口/地址权限（序列号：用户在 dialout 组）
启用 debug: true 详细日志记录的连接参数

HTTP服务器问题：

检查端口是否已在使用中： lsof -i :8000
尝试其他端口： --port 8080
对于远程访问，请确保防火墙允许该端口

工具调用失败：

在调用其他工具之前，请确保您已连接
检查联系人姓名/密钥是否正确
验证设备固件是否与meshcore_py 2.2.1兼容+

BLE配对：

使用 pin 如果您的设备需要配对，请输入参数
确保您的系统已启用蓝牙
检查BLE地址格式是否正确（XX:XX:XX/XX:XX:XX）

OpenWebUI/MCPO问题：

确保MCP服务器正在运行，并且可以在配置的URL上访问
验证MCPO是否可以访问MCP服务器（检查Docker网络设置）
确认URL包括 /mcp 端点： http://localhost:8000/mcp
服务器接受两者 /mcp 和 /mcp/ （带或不带尾随斜线）不重定向
检查MCPO日志： docker logs mcpo
对于远程服务器，确保防火墙规则允许连接
验证 type 设置为 "streamable-http" 在MCPO配置中
如果使用旧版本的MCPO（\=2.2.1）-用于MeshCore设备的Python库
主控程序（>=1.0.0）-使用FastMCP的模型上下文协议SDK

安全考虑

重要：默认情况下，HTTP服务器不包括身份验证。用于生产用途：

部署在具有身份验证的反向代理（nginx、Apache）后面
对加密连接使用HTTPS/TLS
使用防火墙规则限制网络访问
考虑使用SSH隧道进行远程访问
没有适当的安全措施，不要直接暴露在互联网上

Meshcore MCP

快速接入

详细介绍