# 串口智控
## 基本信息
- Slug: `mcp2everything-mcp2serial`
- Source: modelscope
- Publisher: @mcp2everything/mcp2serial
- Categories: home-automation-and-iot / os-automation / developer-tools
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@mcp2everything/mcp2serial
## 简介
一座通过串行通信将物理硬件设备与人工智能大语言模型连接起来的桥梁，允许用户使用自然语言命令控制硬件。
## 安装提示

```bash
python install.py ``` #### macOS用户 ```bash # 下载安装脚本 curl -O https://raw.githubusercontent.com/mcp2everything/mcp2serial/main/install_macos.py # 运行安装脚本 python3 install_macos.py
```

## MCP Server 详情

# MCP2Serial: 连接物理世界与AI大模型的桥梁 

[English](README_EN.md) | 简体中文

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

## 系统架构

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

## 工作流程

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

## 项目愿景

MCP2Serial 是一个将串口设备接入 AI 大模型的项目，它通过 Model Context Protocol (MCP) 将物理世界与 AI 大模型无缝连接。最终实现：
- 用自然语言控制你的硬件设备
- AI 实时响应并调整物理参数
- 让你的设备具备理解和执行复杂指令的能力

## 主要特性

- **智能串口通信**
  - 自动检测和配置串口设备 用户也可指定串口号
  - 支持多种波特率（默认 115200）
  - 实时状态监控和错误处理

- **MCP 协议集成**
  - 完整支持 Model Context Protocol
  - 支持资源管理和工具调用
  - 灵活的提示词系统

## 支持的客户端

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

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

## 支持的 AI 模型

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

### 云端模型
- OpenAI (GPT-4, GPT-3.5)
- Anthropic Claude
- Google Gemini
- AWS Bedrock
- Azure OpenAI
- Google Cloud Vertex AI

### 本地模型
- LM Studio 支持的所有模型
- Ollama 支持的所有模型
- 任何兼容 OpenAI API 的模型

### 准备
Python3.11 或更高版本
Claude Desktop 或 Cline


## 快速开始

### 1. 安装

#### Windows用户
下载 [install.py](https://raw.githubusercontent.com/mcp2everything/mcp2serial/main/install.py) 
```bash
python install.py
```
#### macOS用户
```bash
# 下载安装脚本
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2serial/main/install_macos.py

# 运行安装脚本
python3 install_macos.py
```


#### Ubuntu/Raspberry Pi用户
```bash
# 下载安装脚本
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2serial/main/install_ubuntu.py

# 运行安装脚本
python3 install_ubuntu.py
```


安装脚本会自动完成以下操作：
- ✅ 检查系统环境
- ✅ 安装必要的依赖
- ✅ 创建默认配置文件
- ✅ 配置Claude桌面版（如果已安装）
- ✅ 检查串口设备

### 手动分步安装依赖
```bash
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无需此步。
使用默认配置文件：
```json
{
    "mcpServers": {
        "mcp2serial": {
            "command": "uvx",
            "args": [
                "mcp2serial"
            ]
        }
    }
}
```
> 注意：修改配置后需要重启Cline或者Claude客户端软件

配置串口和命令：
注意下面的配置默认为COM11 需要根据实际进行修改
```yaml
# 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. 用户主目录（推荐个人使用）
```bash
# Windows系统
C:\Users\用户名\.mcp2serial\config.yaml

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

# Linux系统
/home/用户名/.mcp2serial/config.yaml
```
- 适用场景：个人配置
- 需要创建 `.mcp2serial` 目录：
  ```bash
  # Windows系统（在命令提示符中）
  mkdir "%USERPROFILE%\.mcp2serial"
  
  # macOS/Linux系统
  mkdir -p ~/.mcp2serial
  ```

#### 3. 系统级配置（适合多用户环境）
```bash
# Windows系统（需要管理员权限）
C:\ProgramData\mcp2serial\config.yaml

# macOS/Linux系统（需要root权限）
/etc/mcp2serial/config.yaml
```
- 适用场景：多用户共享配置
- 创建目录并设置权限：
  ```bash
  # 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` 中添加自定义命令：
默认不使用真实串口 用模拟串口来演示则无需修改
```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调到一半"
```


使用真实串口
```yaml
# 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
```json
{
    "mcpServers": {
        "mcp2serial": {
            "command": "uvx",
            "args": [
                "mcp2serial",
                "--config",
                "Pico"  //指定配置文件名，不需要添加_config.yaml后缀
            ]
        }
    }
}
```
为了能使用多个串口，我们可以新增多个mcp2serial的服务 指定不同的配置文件名即可。
如果要接入多个设备，如有要连接第二个设备：
指定加载Pico2配置文件：Pico2_config.yaml
```json
{
    "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/conn
ect.jpg" alt="硬件连接示例" width="600"/>
    <p>硬件连接和COM端口配置</p>
</div>

### 启动客户端Claude 桌面版或Cline

<div align="center">
    <img src="docs/images/pwm.png" alt="Cline Configuration Example" width="600"/>
    <p> Claude中的示例</p>
</div>
<div align="center">
 …