MCP2系列：连接物理世界与AI大模型的桥梁

English | 简体中文

<div align="center"> <img src="docs/images/logo.png" alt="MCP2系列Logo" width="200"/> <p>通过自然语言控制硬件，开启物联网新纪元</p> </div>

系统架构

<div align="center"> <img src="docs/images/stru_chs.png" alt="系统架构图" width="800"/> <p>MCP2系列系统架构图</p> </div>

工作流程

<div align="center"> <img src="docs/images/workflow_chs.png" alt="工作流程图" width="800"/> <p>MCP2系列工作流程图</p> </div>

项目愿景

MCP2系列将串行设备连接到AI大模型项目，通过模型上下文协议（MCP）无缝链接物理世界与AI大模型。最终实现：

• 使用自然语言控制硬件设备
• AI实时响应并调整物理参数
• 赋予设备理解并执行复杂指令的能力

主要特性

• 智能串行通信

  • 自动检测和配置串行设备。用户也可以指定串口编号
  • 支持多种波特率（默认115200）
  • 实时状态监控和错误处理

• MCP协议集成

  • 完整支持模型上下文协议
  • 支持资源管理和工具调用
  • 灵活的提示词系统

支持的客户端

MCP2系列支持所有实现了MCP协议的客户端，包括：

客户端	功能支持	描述
Claude Desktop	全部支持	推荐使用，支持所有MCP功能
Continue	全部支持	优秀的开发工具集成
Cline	资源+工具	支持多个AI提供商
Zed	基础支持	支持提示词命令
Sourcegraph Cody	资源支持	通过OpenCTX集成
Firebase Genkit	部分支持	支持资源列表和工具

支持的AI模型

得益于灵活的客户端支持，MCP2系列可以与多个AI模型协同工作：

云端模型

• OpenAI (GPT-4, GPT-3.5)
• Anthropic Claude
• Google Gemini
• AWS Bedrock
• Azure OpenAI
• Google Cloud Vertex AI

本地模型

• 所有LM Studio支持的模型
• 所有Ollama支持的模型
• 任何兼容OpenAI API的模型

准备

Python 3.11或更高版本 Claude Desktop 或 Cline

快速开始

1. 安装

Windows 用户

下载 install.py

python install.py

MacOS 用户

# 下载安装脚本
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2serial/main/install_macos.py

# 运行安装脚本
python3 install_macos.py

Ubuntu/Raspberry Pi 用户

# 下载安装脚本
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2serial/main/install_ubuntu.py

# 运行安装脚本
python3 install_ubuntu.py

安装脚本将自动完成以下操作：

• ✅ 检查系统环境
• ✅ 安装必要的依赖项
• ✅ 创建默认配置文件
• ✅ 配置Claude桌面版（如果已安装）
• ✅ 检查串口设备

手动逐步安装依赖项

Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
MacOS
curl -LsSf https://astral.sh/uv/install.sh | sh

主要依赖于UV工具，因此一旦安装了Python、UV以及Claude或Cline，就可以完成了。

基本配置

在您的MCP客户端（如Claude Desktop或Cline）配置文件中添加以下内容： 注意：如果使用自动安装，Calude Desktop将被自动配置，无需此步骤。 使用默认配置文件：

{
    "mcpServers": {
        "mcp2serial": {
            "command": "uvx",
            "args": [
                "mcp2serial"
            ]
        }
    }
}

注意：修改配置后，需要重启Cline或Claude客户端软件

配置串口和命令： 请注意，以下配置默认为COM11，需要根据实际情况进行修改

# config.yaml
serial:
  port: COM11  # 或自动检测
  baud_rate: 115200  # 可选，默认 115200
  timeout: 1.0  # 可选，默认 1.0
  read_timeout: 1.0  # 读取超时时间，1秒内不应答则报错
  response_start_string: OK  # 可选，串口应答的开始字符串，默认为OK

commands:
  set_pwm:
    command: "PWM {frequency}\n"
    need_parse: false
    prompts:
      - "把PWM调到{value}"

配置说明

配置文件位置

配置文件（config.yaml）可以放置在不同位置，程序将按以下顺序搜索：

1. 当前工作目录（适用于开发和测试）

• 路径：./config.yaml
• 示例：如果您在 C:\Projects 运行程序，它将搜索 C:\Projects\config.yaml
• 适用场景：开发和测试
• 不需要特殊权限

2. 用户主目录（推荐用于个人使用）

# Windows系统
C:\Users\用户名\.mcp2serial\config.yaml

# macOS系统
/Users/用户名/.mcp2serial/config.yaml

# Linux系统
/home/用户名/.mcp2serial/config.yaml

• 适用场景：个人配置
• 需要创建 .mcp2serial 目录

  # Windows系统（在命令提示符中）
  mkdir "%USERPROFILE%\.mcp2serial"
  
  # macOS/Linux系统
  mkdir -p ~/.mcp2serial
  

3. 系统级配置（适用于多用户环境）

# Windows系统（需要管理员权限）
C:\ProgramData\mcp2serial\config.yaml

# macOS/Linux系统（需要root权限）
/etc/mcp2serial/config.yaml

• 适用场景：多用户共享配置
• 创建目录并设置权限：

  # Windows系统（以管理员身份运行）
  mkdir "C:\ProgramData\mcp2serial"
  
  # macOS/Linux系统（以root身份运行）
  sudo mkdir -p /etc/mcp2serial
  sudo chown root:root /etc/mcp2serial
  sudo chmod  755 /etc/mcp2serial
  

程序将按上述顺序搜索配置文件，并使用找到的第一个有效配置文件。根据需求选择合适的存放位置：

• 开发测试：使用当前目录
• 个人使用：推荐使用用户的主目录（推荐）
• 多用户环境：使用系统级配置（ProgramData或/etc）

串口配置命令的高级配置

在 config.yaml 中添加自定义命令： 如果默认使用模拟串口而不是真实的串口进行演示，则无需修改

serial:
  # 串口配置
  port: LOOP_BACK  # 可选，如果不指定则自动查找。设置为LOOP_BACK时启用回环模式，发送什么就接收什么
  baud_rate: 115200  # 可选，默认 115200
  timeout: 1.0  # 可选，默认 1.0
  read_timeout: 1.0  # 读取超时时间，1秒内不应答则报错
  response_start_string: CMD  # 可选，串口应答的开始字符串，默认为OK

commands:
  # PWM控制命令
  set_pwm:
    command: "CMD_PWM {frequency}"  # 实际发送的命令格式，server会自动添加\r\n
    need_parse: false  # 不需要解析响应内容
    prompts:
      - "把PWM调到最大"
      - "把PWM调到最小"
      - "请将PWM设置为{value}"
      - "关闭PWM"
      - "把PWM调到一半"

使用真实串口

# config.yaml
serial:
  port: COM11  # 或自动检测
  baud_rate: 115200  # 可选，默认 115200
  timeout: 1.0  # 可选，默认 1.0
  read_timeout: 1.0  # 读取超时时间，1秒内不应答则报错
  response_start_string: OK  # 可选，串口应答的开始字符串，默认为OK

commands:
  set_pwm:
    command: "PWM {frequency}\n"
    need_parse: false
    prompts:
      - "把PWM调到{value}"

指定配置文件： 例如，指定加载Pico配置文件：Pico_config.yaml

{
    "mcpServers": {
        "mcp2serial": {
            "command": "uvx",
            "args": [
                "mcp2serial",
                "--config",
                "Pico"  //指定配置文件名，不需要添加_config.yaml后缀
            ]
        }
    }
}

为了使用多个串口，我们可以添加多个mcp2serial服务并指定不同的配置文件名。 如果需要连接多个设备，并且需要连接第二个设备： 指定加载Pico2配置文件：Pico2.config.yaml

{
    "mcpServers": {
        "mcp2serial2": {
            "command": "uvx",
            "args": [
                "mcp2serial",
                "--config",
                "Pico2"  //指定配置文件名，不需要添加_config.yaml后缀
            ]
        }
    }
}

响应分析解释

1. 简单响应（need_parse: false）：

   • 设备返回以“OK”开头的消息表示成功
   • 其他响应将被视为错误

2. 需要解析的响应（need_parse: true）：

   • 提供完整的响应 result.raw 字段返回
   • 应用层可以进一步分析

硬件连接

1. 将设备通过USB连接到计算机
2. 打开设备管理器并记录设备的COM端口号
3. 在config.yaml中间配置正确的端口号和波特率

<div align="center"> <img src="docs/images/connect.jpg" alt="硬件连接示例" width="600"/> <p>硬件连接和COM端口配置</p> </div>

启动Claude桌面或Cline客户端

<div align="center"> <img src="docs/images/pwm.png" alt="Cline配置示例" width="600"/> <p>Claude示例</p> </div> <div align="center"> <img src="docs/images/test_output.png" alt="Cline配置示例" width="600"/> <p>Cline示例</p> </div>

硬件编程

固件可以从项目仓库下载，当前演示是Pico的micropython代码案例。只需将其保存到Pico开发板并运行即可。

从源代码快速启动

1. 从源代码安装

# 通过源码安装：
git clone https://github.com/mcp2everything/mcp2serial.git
cd mcp2serial

# 创建虚拟环境
uv venv .venv

# 激活虚拟环境
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

# 安装开发依赖
uv pip install --editable .

2. 配置串口和命令： 默认不使用真实串口，使用模拟串口进行演示 如果您的计算机没有串口或目前没有可用的串口 您可以将端口参数设置为LOOP_ACK，这样可以直接在命令行上发送命令 但同时，请修改响应OK命令的起始字符，使其与发送的命令相同。 例如，发送LED_SON 因此，响应的起始符号也是LED_SON

serial:
  # 串口配置
  port: LOOP_BACK  # 可选，如果不指定则自动查找。设置为LOOP_BACK时启用回环模式，发送什么就接收什么
  baud_rate: 115200  # 可选，默认 115200
  timeout: 1.0  # 可选，默认 1.0
  read_timeout: 1.0  # 读取超时时间，1秒内不应答则报错
  response_start_string: CMD  # 可选，串口应答的开始字符串，默认为OK

commands:
  # PWM控制命令
  set_pwm:
    command: "CMD_PWM {frequency}"  # 实际发送的命令格式，server会自动添加\r\n
    need_parse: false  # 不需要解析响应内容
    prompts:
      - "把PWM调到最大"
      - "把PWM调到最小"
      - "请将PWM设置为{value}"
      - "关闭PWM"
      - "把PWM调到一半"

如果使用真实串口

# config.yaml
serial:
  port: COM11  # 或自动检测
  baud_rate: 115200  # 可选，默认 115200
  timeout: 1.0  # 可选，默认 1.0
  read_timeout: 1.0  # 读取超时时间，1秒内不应答则报错
  response_start_string: OK  # 可选，串口应答的开始字符串，默认为OK

commands:
  set_pwm:
    command: "PWM {frequency}\n"
    need_parse: false
    prompts:
      - "把PWM调到{value}"

MCP客户端配置

当使用支持MCP协议的客户端（如Claude Desktop或Cline）时，需要在客户端的配置文件中添加以下内容： 直接自动安装配置方法 源代码开发配置方法

使用默认演示参数：

{
    "mcpServers": {
        "mcp2serial": {
            "command": "uv",
            "args": [
                "--directory",
                "你的实际路径/mcp2serial",  // 例如: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2serial"
                "run",
                "mcp2serial"
            ]
        }
    }
}

指定参数文件名

{
    "mcpServers": {
        "mcp2serial": {
            "command": "uv",
            "args": [
                "--directory",
                "你的实际路径/mcp2serial",  // 例如: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2serial"
                "run",
                "mcp2serial",
                "--config", // 可选参数，指定配置文件名
                "Pico"  // 可选参数，指定配置文件名，不需要添加_config.yaml后缀
            ]
        }
    }
}

3. 运行服务器：

# 确保已激活虚拟环境
.venv\Scripts\activate

# 运行服务器（使用默认配置config.yaml 案例中用的LOOP_BACK 模拟串口，无需真实串口和串口设备）
uv run src/mcp2serial/server.py
或
uv run mcp2serial
# 运行服务器（使用指定配置Pico_config.yaml）
uv run src/mcp2serial/server.py --config Pico
或
uv run mcp2serial --config Pico

文档

• 安装指南
• API文档
• 配置说明

应用场景

1. 智能家居自动化

   • 通过自然语言控制照明、风扇和其他设备
   • AI根据环境自动调整设备参数

2. 工业自动化

   • 智能控制生产线设备
   • 实时监测和调整工艺参数

3. 教育和研究

   • 物联网教学演示
   • 硬件控制实验平台

4. 原型设计

   • 快速验证硬件控制解决方案
   • 简化开发过程

🚀 项目开发规划

第一阶段：协议扩展

• 工业协议支持

  • MODBUS RTU/TCP
  • OPC UA
  • MQTT
  • CoAP
  • TCP/IP Socket

• 硬件接口扩展

  • I2C
  • SPI
  • CAN
  • 1-Wire
  • GPIO

第二阶段：MCP2Anything平台

• 统一集成平台

  • 视觉配置界面
  • 一键激活各种协议
  • 实时监控仪表盘
  • 设备管理系统

• 智能功能

  • 协议自动检测
  • 自动设备发现
  • 智能参数优化
  • 异常预警系统

第三阶段：生态系统建设

• 插件市场

  • 协议插件
  • 设备驱动
  • 自定义功能模块
  • 社区贡献整合

• 云服务集成

  • 设备云管理
  • 远程控制
  • 数据分析
  • AI训练平台

第四阶段：行业解决方案

• 垂直领域适应

  • 工业自动化
  • 智能建筑
  • 农业物联网
  • 智慧城市

• 定制化服务

  • 行业协议适配