Umeko Serial MCP

基于 MCP 协议的本地串口通信服务，内置实时 Web 监控面板。
通过自然语言让 AI 助手与你的单片机、嵌入式设备直接对话。

✨ 功能特性

• 🖥️ MCP 支持 — 通过 Model Context Protocol 与 AI 客户端无缝集成
• 🔌 串口控制 — 自动扫描、连接、读写串口设备
• 🌐 Web 监控面板 — 内置 HTTP + WebSocket 双端口服务，浏览器实时旁路监控
• 兼容 Windows, MacOS, Linux

---

🛠️ 可用工具

工具	说明
list_ports	扫描本机所有可用串口
connect_port	连接指定串口（支持自定义波特率，默认 115200）
close_port	显式断开当前串口连接
write_data	向串口写入数据（自动补全换行符）
read_data	读取串口缓冲区数据（含用户干预历史）
start_monitor_ui	启动 Web 监控面板（默认 HTTP 8080 / WebSocket 8081）

---

📦 直接配置到AI助手中（推荐）

本项目已经打包上传到了uv与pypi仓库，各大AI助手中可以直接通过以下命令行添加，会自动拉取并配置。

通过命令行添加

# claude code
claude mcp add serial-mcp -- uvx --from umeko-serial-mcp start-serial-mcp

# codex
codex mcp add serial-mcp -- uvx --from umeko-serial-mcp start-serial-mcp

使用 mcp.json 添加 (Kimi Code)

Kimi Code 通过 mcp.json 配置 MCP 服务器。编辑用户级配置 ~/.kimi-code/mcp.json（或项目级 .kimi-code/mcp.json），添加以下内容：

{
  "mcpServers": {
    "serial-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "umeko-serial-mcp",
        "start-serial-mcp"
      ]
    }
  }
}

也可以在 Kimi Code 的 TUI 中运行 /mcp-config 交互式添加；配置后运行 /mcp 可查看连接状态。

使用 toml 添加 (Codex)

这是 Codex CLI 默认和推荐的配置格式 。打开你的配置文件（如 ~/.codex/config.toml），添加以下内容：

[mcp_servers.serial-mcp]
command = "uvx"
args = ["--from", "umeko-serial-mcp", "start-serial-mcp"]

通过JSON添加

🦞OpenClaw, Cursor, Cline, TRAE, Cherry Studio, Qwen Chat等其它客户端，在mcp服务器设置中，选择使用json添加并且粘贴以下字段。

{
  "mcpServers": {
    "serial-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "umeko-serial-mcp",
        "start-serial-mcp"
      ]
    }
  }
}

📦 手动下载安装运行

如果你想要自定义修改本工具使用。

方式一：通过 Python 安装

# 使用 uvx 直接运行（无需安装）
uvx --from umeko-serial-mcp start-serial-mcp

或使用 pip：

pip install umeko-serial-mcp
start-serial-mcp

方式二：本地开发安装

1. 克隆仓库

git clone https://github.com/umeiko/umeko_serial_mcp.git
cd umeko_serial_mcp

2. 安装依赖

确保已安装 uv：

uv sync

3. 本地运行

# 直接运行源码
uv run start-serial-mcp

# 或者先构建 wheel 再通过 uvx 运行（推荐，避免源码缓存问题）
uv build --wheel
uvx --from . start-serial-mcp

⚠️ 开发注意：uvx --from . 会缓存 wheel 包，修改源码后需先升级 pyproject.toml 版本号，再执行 uv build --wheel，最后重启 MCP 客户端才能生效。

---

⚙️ 客户端配置示例

如果要让客户端使用你本地部署的本服务，在支持 MCP 的客户端（如 Claude-code、Cursor、Cline 等）的 mcp.json 中添加：

{
  "mcpServers": {
    "serial-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "/path/to/umeko_serial_mcp",
        "start-serial-mcp",
        "--reinstall"
      ]
    }
  }
}

将 /path/to/umeko_serial_mcp 替换为本地路径（如 /home/user/umeko_serial_mcp），并加上 --reinstall 参数强制刷新缓存。

配置保存并重启客户端后，即可通过自然语言调用串口功能。

---

🚀 快速开始

使用类似提示词：

请使用串口工具，连接到我的esp32开发板并且测试通信

启动后，AI 会自动执行以下初始化检查：

1. start_monitor_ui    → 启动 Web 面板 http://localhost:8080
2. list_ports          → 发现 /dev/cu.usbmodem101
3. connect_port        → 连接 ESP32（115200）
4. write_data("hello")     → 测试通信
5. read_data()          → 读取串口输入

在浏览器中打开 http://localhost:8080，你可以：

• 🔘 手动控制串口连接/断开
• 💬 实时查看 LLM 与单片机的全部对话
• ✏️ 手动下发命令（旁路干预）