# putty_mcp **Repository Path**: awol2010ex/putty_mcp ## Basic Information - **Project Name**: putty_mcp - **Description**: **PuTTY MCP Server** 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的 Rust 服务器,用于通过 JSON-RPC 协议操作当前运行中的 PuTTY 窗口 (仅支持 Windows,主要用于堡垒机打开的putty会话窗口的操作) 。 它允许 AI 助手(如 Claude Desk - **Primary Language**: Rust - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-02 - **Last Updated**: 2026-09-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # PuTTY MCP Server **PuTTY MCP Server** 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的 Rust 服务器,用于通过 JSON-RPC 协议操作当前运行中的 PuTTY 窗口 (仅支持 Windows,主要用于堡垒机打开的putty会话窗口的操作) 。 它允许 AI 助手(如 Claude Desktop)或任何 MCP 客户端直接向 PuTTY 终端会话发送文本、命令和特殊按键,并读取会话日志。 --- ## 功能特性 - ✅ **列举会话** — 自动发现所有运行中的 PuTTY 窗口 - ✅ **发送文本** — 向指定 PuTTY 窗口发送任意文本内容 - ✅ **发送命令** — 发送命令并自动追加回车执行 - ✅ **危险命令自动拦截** — 拦截 `rm -rf /`、磁盘覆盖、fork 炸弹等破坏性命令 - ✅ **阻塞型命令自动拦截** — 拦截 `top`、`less`、`ping`、`watch` 等会持续占用终端的命令 - ✅ **特殊按键** — 支持 Enter、Tab、Backspace、Escape 等按键 - ✅ **Ctrl 组合键** — 支持 Ctrl+C、Ctrl+D、Ctrl+Z 等组合键 - ✅ **窗口激活** — 将指定 PuTTY 窗口置于前台 - ✅ **日志读取** — 读取 PuTTY 会话日志文件 (putty.log) - ✅ **MCP 标准协议** — 完全兼容 MCP 2024-11-05 协议规范 --- ## 系统要求 - **操作系统**: Windows (7/10/11) - **Rust 工具链**: 1.75+(仅编译时需要) - **PuTTY**: 需安装并运行 PuTTY 终端会话 - **PuTTY 日志**: 需开启会话日志记录(见下方配置说明) --- ## 安装方法 ### 方法一:从源码编译 ```bash # 克隆仓库 git clone <仓库地址> cd putty_mcp # 编译发布版本 cargo build --release # 可执行文件位于 # target/release/putty_mcp.exe ``` ### 方法二:直接下载(待提供) 从 [Releases](../../releases) 页面下载预编译的 `putty_mcp.exe` 文件。 --- ## 使用 cargo mcp-stdio-run 安装(免本地编译) [`cargo-mcp-stdio-run`](https://crates.io/crates/cargo-mcp-stdio-run) 是一个类 `npx` 的 cargo 子命令:从 crates.io 拉取、编译任意 Rust 二进制,并以 **stdout 纯净** 的方式运行——专为 MCP stdio 场景设计。首次运行会拉取源码并编译(结果缓存到 `~/.cargo-mcp-stdio-run`),之后命中缓存秒级启动,无需本地 `git clone` / `cargo build`。 > 前置:先安装该子命令(一次即可) > ```bash > # 已从 crates.io 发布(当前 v0.0.1),直接安装即可: > cargo install cargo-mcp-stdio-run > # 想尝鲜未发布改动时,可改用源码路径(例如 D:\workspace_rust\cargo-mcp): > # cargo install --path D:\workspace_rust\cargo-mcp > ``` 直接用 crate 名运行(本服务无需启动参数,仅支持 Windows): ```bash cargo mcp-stdio-run putty_mcp ``` 在 MCP 客户端(如 Claude Desktop)里的配置: ```json { "mcpServers": { "putty": { "command": "cargo", "args": ["mcp-stdio-run", "putty_mcp"] } } } ``` ## 配置 PuTTY 日志 为了读取会话输出,需要在 PuTTY 中开启日志记录: 1. 打开 PuTTY 2. 配置好您的 SSH 会话 3. 在左侧导航栏选择 **Session → Logging** 4. 在 **Logging** 页面: - 选择 **"All session output"** - 在 **Log file name** 中输入 `putty.log` 5. 返回 **Session** 页面,点击 **Save** 保存会话配置 6. **重新连接** 会话以生成日志文件 日志文件 `putty.log` 会保存在 `putty.exe` 所在目录(通常是 `C:\Program Files\PuTTY\` 或您安装的目录)。 --- ## 使用方法 ### 作为 MCP 服务器运行 ```bash # 启动 STDIO 模式(默认) putty_mcp.exe # 查看帮助 putty_mcp.exe --help # 查看版本 putty_mcp.exe --version # 查看服务器信息 putty_mcp.exe --info ``` ### 与 Claude Desktop 集成 在 Claude Desktop 的 `claude_desktop_config.json` 中添加: ```json { "mcpServers": { "putty": { "command": "D:\\path\\to\\putty_mcp.exe", "args": [] } } } ``` ### 手动测试 JSON-RPC 请求 服务器通过 STDIN/STDOUT 接收和响应 JSON-RPC 请求(每行一个 JSON): ```json {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}} {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}} {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_sessions","arguments":{}}} {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"send_command","arguments":{"command":"ls -la"}}} {"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"read_log","arguments":{"max_bytes":5000}}} ``` --- ## 可用工具参考 ### 1. `list_sessions` 列出所有运行中的 PuTTY 窗口。 **参数**: 无 **示例响应**: ```json { "success": true, "sessions": [ { "id": "uuid-xxx", "window_title": "root@myserver", "hwnd": "0x123456", "pid": 12345, "is_visible": true, "discovered_at": "2025-01-01T00:00:00Z" } ], "count": 1 } ``` ### 2. `send_text` 向 PuTTY 窗口发送文本(不自动添加回车)。 **参数**: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | `text` | string | 是 | 要发送的文本内容 | | `session_id` | string | 否 | 会话ID(留空使用当前会话) | ### 3. `send_command` 发送命令并自动追加回车执行。 > ⚠️ **安全过滤**:危险命令(如 `rm -rf /`、磁盘覆盖、fork 炸弹等)和阻塞型命令(如 `top`、`less`、`ping`、`ssh` 等)会被自动拦截,请使用安全替代方案(见下方命令过滤说明)。 **参数**: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | `command` | string | 是 | 要执行的命令 | | `session_id` | string | 否 | 会话ID(留空使用当前会话) | ### 4. `send_key` 发送特殊按键。 **参数**: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | `key` | string | 是 | 按键名称: `enter`, `backspace`, `tab`, `escape`, `ctrl+c`, `ctrl+d`, `ctrl+z` 等 | | `session_id` | string | 否 | 会话ID(留空使用当前会话) | ### 5. `activate_session` 将 PuTTY 窗口置于前台。 **参数**: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | `session_id` | string | 否 | 会话ID(留空使用当前会话) | ### 6. `get_session_info` 获取指定会话的详细信息。 **参数**: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | `session_id` | string | 否 | 会话ID(留空使用当前会话) | ### 7. `set_current_session` 设置当前活动会话。 **参数**: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | `session_id` | string | 是 | 会话ID | ### 8. `refresh_sessions` 刷新会话列表(重新枚举所有 PuTTY 窗口)。 **参数**: 无 ### 9. `get_log_path` 获取 PuTTY 日志文件路径。 **参数**: 无 ### 10. `read_log` 读取 PuTTY 日志文件内容。 **参数**: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | `max_bytes` | integer | 否 | 最大读取字节数(默认读取全部) | --- ## 命令过滤说明 `send_command` 和 `send_text` 工具内置了双重安全过滤器,在命令发送到远程终端前自动拦截不安全操作。 ### 第一层:危险破坏命令过滤 拦截可能对远程系统造成破坏的命令: | 分类 | 拦截示例 | 安全替代方案 | |------|---------|-------------| | 💀 **系统破坏** | `rm -rf /` | `rm -rf ./temp`(相对路径) | | 💀 **Fork 炸弹** | `:(){ :\|:& };:` | `ulimit -u`(查看进程限制) | | 💾 **磁盘覆盖** | `dd if=/dev/zero of=/dev/sda` | `dd of=/tmp/testfile`(写入普通文件) | | 💾 **磁盘格式化** | `mkfs.ext4 /dev/sdb1` | 禁止在运行系统中格式化 | | 🔌 **系统关机** | `shutdown`, `reboot`, `halt` | `exit` 或 Ctrl+D 退出会话 | | 🔒 **权限锁定** | `chmod -R 000 /` | `chmod -R 755 /var/www`(具体目录) | | 🌐 **远程下载执行** | `curl ... \| sh` | 先下载审查再执行 | ### 第二层:阻塞型命令过滤 拦截会持续占用终端、不会自动退出的命令: | 分类 | 拦截命令 | 放行条件 | 安全替代方案 | |------|---------|---------|-------------| | 📺 **交互式 TUI** | `top`, `htop`, `less`, `vim`, `mc`, `screen` | `top -b -n 1`(批处理) | `top -b -n 1` 或 `ps aux` | | 📊 **持续输出** | `tail -f`, `ping`, `watch`, `tcpdump` | `ping -c 4`(指定次数) | `tail -n 50`, `ping -c 4` | | 🔗 **嵌套连接** | `ssh`, `telnet`, `nc` | 无 | 使用新 PuTTY 窗口 | ### 智能识别 过滤器对带有 `sudo` 前缀的命令同样生效,并能识别安全参数: | 命令 | 结果 | |------|------| | `top` | ❌ 拦截 — 交互模式需按 q 退出 | | `top -b -n 1` | ✅ 放行 — 批处理模式,输出一次后退出 | | `ping 8.8.8.8` | ❌ 拦截 — 无限持续 | | `ping -c 4 8.8.8.8` | ✅ 放行 — 发送 4 次后退出 | | `sudo less /var/log/syslog` | ❌ 拦截 — 分页器交互模式 | | `tail -f /var/log/syslog` | ❌ 拦截 — 跟踪模式持续输出 | | `tail -n 50 /var/log/syslog` | ✅ 放行 — 一次性输出 | | `iostat -x 1` | ❌ 拦截 — 有间隔无次数,无限执行 | | `iostat -x 1 3` | ✅ 放行 — 3 次后退出 | --- ## 工作流程示例 典型的 AI 助手使用流程: 1. **`list_sessions`** — 发现可用的 PuTTY 会话 2. **`send_command`** — 发送命令(如 `cd /var/log`) 3. **`read_log`** — 读取命令输出 4. **`send_command`** — 发送下一个命令 5. **`read_log`** — 读取输出结果 6. 重复步骤 4-5 直到任务完成 --- ## 开发指南 ### 项目结构 ``` src/ ├── main.rs # MCP 服务器入口 + STDIO 通信循环 ├── core.rs # 核心数据结构 (PuttyManager, PuttySession) ├── handlers.rs # JSON-RPC 请求解析与分发 ├── utils.rs # Windows API 封装层 └── tools/ ├── mod.rs # 工具模块声明 ├── filter.rs # 命令安全检查过滤器(危险命令 + 阻塞型命令拦截) └── session.rs # 会话操作工具实现 ``` ### 构建与测试 ```bash # 编译 cargo build # 运行测试 cargo test # 发布编译 cargo build --release ``` ### 添加新工具 1. 在 `src/tools/session.rs` 的 `SessionTool` 中添加新方法 2. 在 `src/handlers.rs` 的 `list_tools()` 中添加工具定义 3. 在 `src/handlers.rs` 的 `call_tool()` 中添加路由 --- ## 技术原理 本服务器通过 Windows API 直接操作 PuTTY 窗口: | 操作 | Windows API | |------|-------------| | 查找窗口 | `EnumWindows` + `GetClassNameW` 过滤类名 `"PuTTY"` | | 发送文本 | `PostMessageW` + `WM_CHAR` 逐字符发送 | | 发送按键 | `WM_KEYDOWN` / `WM_KEYUP` 虚拟键码 | | Ctrl 组合 | `WM_KEYDOWN(Ctrl)` → `WM_CHAR(1-26)` → `WM_KEYUP(Ctrl)` | | 定位进程 | `tasklist` → `OpenProcess` → `QueryFullProcessImageNameW` | | 日志路径 | 从 putty.exe 路径推导 `putty.log` 位置 | --- ## 许可证 Apache License 2.0 ---