mcp-remote-access

🚀 SSH与串口远程访问服务

本项目是一个MCP服务器，为兼容MCP的客户端（如Codex CLI或Claude Code）提供SSH和UART/串口访问功能。借助该项目，你可以直接控制树莓派、嵌入式系统和物联网设备等远程设备。

🚀 快速开始

本项目为兼容MCP的客户端提供SSH和串口访问功能，可直接控制远程设备。以下是使用步骤：

1. 克隆并安装项目
2. 将其添加到你的MCP客户端
3. 启动客户端

✨ 主要特性

SSH工具

• ssh_connect - 通过SSH（密码或密钥认证）连接到远程主机
• ssh_execute - 在已连接的主机上运行命令
• ssh_upload - 通过SFTP上传文件
• ssh_download - 通过SFTP下载文件
• ssh_disconnect - 关闭连接
• ssh_list_connections - 显示活动连接

UART/串口工具

• serial_list_ports - 列出可用的串口
• serial_connect - 连接到串口
• serial_connect_match - 通过匹配VID/PID/序列号/描述信息来连接
• serial_send - 发送数据（可选择读取响应并配置行尾符）
• serial_read - 从端口读取数据
• serial_wait_for - 等待输出中出现特定模式
• serial_expect - 等待/发送序列以处理提示和AT流程
• serial_send_break - 发送中断信号
• serial_set_dtr - 设置DTR线路状态
• serial_set_rts - 设置RTS线路状态
• serial_reset_device - 通过DTR/RTS序列重置设备
• serial_flush - 刷新串口缓冲区
• serial_disconnect - 关闭连接
• serial_list_connections - 显示活动连接

📦 安装指南

1. 克隆并安装

git clone https://github.com/RFingAdam/mcp-remote-access.git
cd mcp-remote-access
uv pip install -e .

2. 添加到你的MCP客户端

Codex CLI示例

codex mcp add remote-access -- uv run --directory /path/to/mcp-remote-access mcp-remote-access

Claude Code示例

claude mcp add remote-access -- uv run --directory /path/to/mcp-remote-access mcp-remote-access

如果你的客户端使用配置文件，请将MCP服务器命令设置为：

{
  "command": "uv",
  "args": ["run", "--directory", "/path/to/mcp-remote-access", "mcp-remote-access"]
}

3. 启动你的客户端

例如：

codex

claude

💻 使用示例

基础用法

SSH连接到树莓派

使用用户名 pi 和密码 raspberry 连接到位于 vpn-ap.local 的树莓派

客户端将使用以下步骤：

1. 使用 ssh_connect 建立连接
2. 使用 ssh_execute 运行命令
3. 使用 ssh_upload/download 进行文件传输

串口连接到嵌入式设备

列出可用的串口并以115200波特率连接到 /dev/ttyUSB0

客户端将使用以下步骤：

1. 使用 serial_list_ports 显示可用端口
2. 使用 serial_connect 建立连接
3. 使用 serial_send / serial_read 进行通信

以115200波特率连接到VID为0x10c4、PID为0xea60的USB串口设备

客户端将使用以下步骤：

1. 使用 serial_connect_match 选择端口
2. 使用 serial_send / serial_read 进行通信

串口提示自动化

连接到UART并以root用户（密码为summit）登录，然后等待shell提示

客户端将使用以下步骤：

1. 使用 serial_connect 或 serial_connect_match 打开端口
2. 使用 serial_expect 等待提示并发送响应

🔧 技术细节

安全注意事项

• SSH密码仅在内存中传递，不会被存储。
• 连接基于会话，服务器重启时会清除。
• 尽可能使用SSH密钥以提高安全性。
• 服务器仅接受来自本地MCP客户端的连接（标准输入输出传输）。

故障排除

SSH连接问题

• 验证主机是否可达：ping vpn-ap.local
• 检查目标主机上的SSH是否正在运行：ssh pi@vpn-ap.local
• 确保凭证正确。

串口问题

• 检查端口权限：ls -la /dev/ttyUSB*
• 将用户添加到dialout组：sudo usermod -a -G dialout $USER
• 验证设备是否已连接：dmesg | tail

📄 许可证

本项目采用MIT许可证。