# serial-mcp-server

**Repository Path**: printe/serial-mcp-server

## Basic Information

- **Project Name**: serial-mcp-server
- **Description**: 完全由AI生成的MCP串口
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-30
- **Last Updated**: 2026-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Serial MCP Server

串口通信工具与 MCP 服务器 — 基于 Model Context Protocol 的串口控制服务。

**跨平台**：Windows / Linux / macOS  
**特性**：config.yaml 动态命令、DTR/RTS 复位控制、自动端口检测、独立 EXE 打包

---

## 快速安装

### 方式一：pip 安装（推荐）

```bash
# 克隆项目后
pip install .
# 或带开发依赖
pip install ".[dev]"

# 启动
serial-mcp-server --config config.yaml
```

> **注意**：`pip install .` 是**非可编辑安装**，将代码复制到 Python 的 site-packages 中，
> 之后删除或移动源码文件夹不影响运行。如需修改源码后实时生效，用 `pip install -e .`（可编辑模式）。

### 方式二：使用安装脚本

| 平台 | 脚本 |
|------|------|
| Windows | `scripts\install.bat` |
| Linux/macOS | `bash scripts/install.sh` |

### 方式三：Makefile（跨平台）

```bash
make install     # 安装
make run         # 启动（默认配置）
make test        # 运行测试
make build-exe   # 打包独立可执行文件
```

---

## 部署清单

### 最小文件集（在其他电脑上部署只需这些）

```
serial-mcp-server/          ← 整个项目目录复制过去
├── pyproject.toml          ← 项目元数据与依赖声明
├── requirements.txt        ← pip 依赖清单
├── config.yaml             ← 配置文件（根据目标环境修改）
└── src/                    ← Python 源码
    ├── __init__.py
    ├── __main__.py
    ├── config.py
    ├── exceptions.py
    ├── models.py
    ├── serial_tool.py
    └── mcp_server.py
```

> 不需要复制 `tests/`、`examples/` 和 `Makefile`，这些是开发辅助文件。

---

## Windows 部署详情

### 安装步骤

```powershell
# 1. 确保 Python 3.10+ 已安装
python --version

# 2. 安装
cd serial-mcp-server
pip install -e .

# 3. 修改 config.yaml 中的串口名称为 Windows 格式
#    port: "COM3"   # 或 "auto" 自动选择
```

### 环境变量 PATH

安装后可执行文件位于：
```
%USERPROFILE%\AppData\Local\Python\pythoncore-3.14-64\Scripts\serial-mcp-server.exe
```

如果命令找不到，将该目录加入 PATH：
```powershell
$oldPath = [Environment]::GetEnvironmentVariable("Path", "User")
$newPath = "$env:USERPROFILE\AppData\Local\Python\pythoncore-3.14-64\Scripts"
[Environment]::SetEnvironmentVariable("Path", "$oldPath;$newPath", "User")
```

### VS Code MCP 配置

#### 方式 A：使用 `cwd` 相对路径（推荐，跨机器可移植）

无需硬编码绝对路径，利用 `cwd` 让服务器自动在项目目录下搜索 `config.yaml`：

```json
{
    "servers": {
        "serial-mcp-server": {
            "type": "stdio",
            "command": "serial-mcp-server",
            "args": [],
            "cwd": "${workspaceFolder}\\serial-mcp-server"
        }
    }
}
```

**原理**：服务器启动后 `cwd` 指向 `serial-mcp-server/` 文件夹，
`config.py` 会自动搜索该目录下的 `config.yaml`（无需 `--config` 参数）。

**跨机器迁移**：整个工作区文件夹复制到新电脑后：
1. 新电脑上执行 `pip install .` 安装一次
2. `${workspaceFolder}` 自动匹配新路径
3. 无需修改任何配置

#### 方式 B：使用绝对路径（明确指定）

```json
{
    "servers": {
        "serial-mcp-server": {
            "type": "stdio",
            "command": "C:\\Users\\<用户名>\\AppData\\Local\\Python\\pythoncore-3.14-64\\Scripts\\serial-mcp-server.exe",
            "args": ["--config", "D:\\path\\to\\config.yaml"]
        }
    }
}
```

### 打包为独立 EXE

```powershell
pip install pyinstaller
pyinstaller --onefile --name serial-mcp-server src/mcp_server.py
# 输出: dist\serial-mcp-server.exe
```

---

## Linux 部署详情

### 安装步骤

```bash
# 1. 确保 Python 3.10+ 已安装
python3 --version

# 2. 安装
cd serial-mcp-server
pip3 install -e .

# 3. 修改 config.yaml 中的串口名称
#    port: "/dev/ttyUSB0"   # Linux 格式
```

### 串口权限

Linux 下访问串口需要用户有 `dialout` 组权限：

```bash
# 将当前用户加入 dialout 组
sudo usermod -a -G dialout $USER
# 注销并重新登录后生效

# 或临时使用 sudo
sudo serial-mcp-server --config config.yaml
```

### 环境变量 PATH

安装后可执行文件位于 `~/.local/bin/serial-mcp-server`。

```bash
# 添加 PATH（如果不在）
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
source ~/.bashrc
```

### VS Code MCP 配置

推荐使用 `cwd` 相对路径方式（跨机器可移植）：

```json
{
    "servers": {
        "serial-mcp-server": {
            "type": "stdio",
            "command": "serial-mcp-server",
            "args": [],
            "cwd": "${workspaceFolder}/serial-mcp-server"
        }
    }
}
```

也可使用绝对路径（不推荐）：

```json
{
    "servers": {
        "serial-mcp-server": {
            "type": "stdio",
            "command": "/home/<用户名>/.local/bin/serial-mcp-server",
            "args": ["--config", "/home/<用户名>/path/to/config.yaml"]
        }
    }
}
```

---

## macOS 部署详情

### 安装步骤

```bash
# 1. 确保 Python 3.10+ (推荐使用 Homebrew)
brew install python
python3 --version

# 2. 安装
cd serial-mcp-server
pip3 install -e .

# 3. 修改 config.yaml 中的串口名称
#    port: "/dev/tty.usbmodemXXXX"   # macOS 格式
```

### 串口权限

macOS 下通常不需要额外权限，但如果遇到拒绝访问：

```bash
# 检查串口设备权限
ls -l /dev/tty.*
# 通常无需手动修改
```

### 环境变量 PATH

```bash
# 添加 PATH
echo 'export PATH="$PATH:$HOME/Library/Python/3.x/bin"' >> ~/.zshrc
source ~/.zshrc
```

---

## 卸载 & 迁移

### 卸载

```bash
pip uninstall serial-mcp-server -y
```

如果提示 `serial-mcp-server.exe` 被占用无法删除：

```bash
# 找到占用进程并终止
tasklist | findstr serial-mcp-server    # Windows: 查看 PID
kill <PID>                               # 终止进程
# 或直接强制删除残留 exe
Remove-Item "$env:USERPROFILE\AppData\Local\Python\pythoncore-3.14-64\Scripts\serial-mcp-server.exe" -Force
```

### 从可编辑安装迁移到独立安装

如果之前用了 `pip install -e .`，安装会**依赖源码位置**，移动/删除文件夹后命令失效。

迁移步骤：

```bash
# 1. 卸载旧版
pip uninstall serial-mcp-server -y

# 2. 删除残留 exe（如卸载时报错）
Remove-Item "$env:USERPROFILE\AppData\Local\Python\pythoncore-3.14-64\Scripts\serial-mcp-server.exe" -Force
# 或手动去该目录删除

# 3. 重新安装（不带 -e，不依赖源码路径）
pip install d:\path\to\serial-mcp-server

# 4. 验证
pip show serial-mcp-server    # 确认没有 "Editable project location" 行
serial-mcp-server --help      # 确认命令可用
```

### 将文件夹移到新位置

```bash
# 1. 移动文件夹（假设从 A:\project 移到 D:\tools）
move A:\project\serial-mcp-server D:\tools\serial-mcp-server

# 2. 重新安装（必须，因为旧安装路径失效）
pip uninstall serial-mcp-server -y
pip install D:\tools\serial-mcp-server

# 3. 更新 VS Code mcp.json 中的 --config 路径
#    将 args 中的旧路径改为新路径
```

---

## 跨平台对比

| 项目 | Windows | Linux | macOS |
|------|---------|-------|-------|
| 串口命名 | `COM3` | `/dev/ttyUSB0` | `/dev/tty.usbmodem` |
| 配置文件路径 | `%APPDATA%\.serial-mcp-server\` | `~/.config/.serial-mcp-server/` | `~/.config/.serial-mcp-server/` |
| 系统配置路径 | `C:\ProgramData\.serial-mcp-server\` | `/etc/.serial-mcp-server/` | `/etc/.serial-mcp-server/` |
| 安装命令 | `pip install -e .` | `pip3 install -e .` | `pip3 install -e .` |
| 执行文件位置 | `%USERPROFILE%\...\Scripts\` | `~/.local/bin/` | `~/Library/Python/3.x/bin/` |
| 权限要求 | 管理员（偶尔） | `dialout` 用户组 | 通常不需要 |
| VS Code 命令路径 | 绝对路径含 `.exe` | 绝对路径或命令名 | 绝对路径或命令名 |

---

## 配置文件 (`config.yaml`)

### 搜索优先级

1. `--config <路径>` 命令行参数
2. `./config.yaml`（当前工作目录）
3. **Windows**: `%APPDATA%\.serial-mcp-server\config.yaml`  
   **Linux/macOS**: `~/.config/.serial-mcp-server/config.yaml`
4. **Windows**: `C:\ProgramData\.serial-mcp-server\config.yaml`  
   **Linux/macOS**: `/etc/.serial-mcp-server/config.yaml`
5. `SERIAL_MCP_*` 环境变量（如 `SERIAL_MCP_BAUDRATE=115200`）
6. 内置默认值

### 完整配置示例

```yaml
serial:
  port: "auto"
  baudrate: 2000000
  bytesize: 8
  parity: "N"
  stopbits: 1.0
  timeout: 1.0
  write_timeout: 1.0
  read_size: 1024
  dtr: false
  rts: false
  xonxoff: false
  rtscts: false
  dsrdtr: false
  break: false

logging:
  level: "INFO"
  file: ""
  log_data_content: false

commands:
  get_help:
    command: "help"
    need_parse: true
    description: "获取帮助"
    prompts: ["获取帮助", "列出命令"]
  set_pwm:
    command: "CMD_PWM {frequency}"
    need_parse: false
    description: "设置 PWM"
    prompts: ["把PWM调到最大"]
```

---

## MCP 工具（13 个）

| 工具 | 功能 |
|------|------|
| `serial_scan` | 扫描可用串口 |
| `serial_connect` | 连接串口（支持 DTR/RTS） |
| `serial_disconnect` | 断开连接 |
| `serial_write` | 写入数据 |
| `serial_writeln` | 写入一行 |
| `serial_read` | 读取数据 |
| `serial_read_line` | 读一行 |
| `serial_read_until` | 读直到指定序列 |
| `serial_read_all` | 读所有可用数据 |
| `serial_status` | 获取状态 |
| `serial_clear` | 清空缓冲区 |
| `serial_set_pin` | 设置 DTR/RTS 引脚 |
| `execute_command` | 执行 config.yaml 命令 |

---

## 常见问题

### Q: 连接串口后单片机复位

如果 CH340/CH343 的 DTR 或 RTS 引脚连接到单片机 RST：

```yaml
serial:
  dtr: false   # 阻止 DTR 触发复位
  rts: false   # 阻止 RTS 触发复位
```

### Q: Linux 下 "Permission denied"

```bash
sudo usermod -a -G dialout $USER
# 注销后重试
```

### Q: macOS 下找不到串口

```bash
# 列出所有串口设备
ls /dev/tty.* /dev/cu.*
```

常见命名：`/dev/tty.usbmodemXXXX`、`/dev/cu.usbserial-XXXX`

### Q: VS Code 报 "spawn ... ENOENT"

使用可执行文件的 **绝对路径**，而不是命令名。具体参见上方各平台的 VS Code 配置示例。