Mcp Ssh Wingman

MCP SSH Wingman

一个模型上下文协议（MCP）服务，通过 tmux 提供对 Unix shell 提示词的只读访问。这使 Claude 等 AI 助手能够安全地查看终端环境，而无需执行命令。

功能

• 🔒 只读访问 - 查看终端内容，无需承担执行风险
• 🖥️ tmux 集成 - 利用 tmux 的会话管理功能，可靠地访问终端
• 📜 回滚历史 - 访问终端历史输出
• 📊 终端元数据 - 获取尺寸、当前路径和会话信息
• 🔌 MCP 协议 - 用于集成 AI 助手的标准协议

常见问题

会添加 GNU screen 支持吗？

近期不会。虽然 screen 可用于结对编程／调试，但它没有任何机制来强制启用只读模式。

由于只读保护是此 MCP 与其他具备 ssh 功能的 MCP 之间的主要区别，因此 screen 需要先支持只读会话，才能集成。

会添加 zellij 支持吗？

将来有可能。需要先实现 https://github.com/zellij-org/zellij/issues/4348，以确保 zellij 具备只读功能，就像 tmux 一样。

前置条件

• tmux（用于管理终端会话）
• （可选）Go 1.21 或更高版本（仅在从源代码构建时需要）

安装

Homebrew（macOS/Linux）

brew tap conallob/tap
brew install mcp-ssh-wingman

预构建二进制文件

从发布页面下载预构建二进制文件。

支持的平台：

• macOS（arm64/amd64）
• Linux（arm64/amd64）
• FreeBSD（arm64/amd64）

从源代码构建

构建说明请参阅 DEVELOPMENT.md。

用法

运行服务

# Start with default tmux session name (mcp-wingman)
mcp-ssh-wingman

# Use a custom tmux session name
mcp-ssh-wingman --session my-session

# Show version
mcp-ssh-wingman --version

与 Claude Desktop 集成

将服务添加到 Claude Desktop 配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ssh-wingman": {
      "command": "/usr/local/bin/mcp-ssh-wingman",
      "args": ["--session", "mcp-wingman"]
    }
  }
}

更新配置后，重启 Claude Desktop。

与 Gemini CLI 集成

将此部分添加到 Gemini 配置文件（~/.gemini/settings.json）：

{
  "mcpServers": {
    "ssh-wingman": {
      "command": "/usr/local/bin/mcp-ssh-wingman",
      "args": ["--session", "mcp-wingman"]
    }
  }
}

运行 gemini CLI，并确认它能够看到 MCP 服务：

> /mcp list

Configured MCP servers:

🟢 ssh-wingman - Ready (3 tools)
  Tools:
  - get_terminal_info
  - read_scrollback
  - read_terminal

使用提示词进行测试：

> using ssh-wingman MCP Server, what do you see in my session?

 ╭────────────────────────────────────────────────────────────────────────────────────────╮
 │ ?  read_terminal (ssh-wingman MCP Server) {} ←                                         │
 │                                                                                        │
 │   MCP Server: ssh-wingman                                                              │
 │   Tool: read_terminal                                                                  │
 │                                                                                        │
 │ Allow execution of MCP tool "read_terminal" from server "ssh-wingma…                   │
 │                                                                                        │
 │ ● 1. Yes, allow once                                                                   │
 │   2. Yes, always allow tool "read_terminal" from server "ssh-wingma…                   │
 │   3. Yes, always allow all tools from server "ssh-wingman"                             │
 │   4. No, suggest changes (esc)                                                         │
 │                                                                                        │
 ╰────────────────────────────────────────────────────────────────────────────────────────╯
⠏ Waiting for user confirmation...

你也可以在那里选择选项 3。

可用工具

该服务提供以下 MCP 工具：

read_terminal

读取 tmux 会话中的当前终端内容。

示例：

{
  "name": "read_terminal"
}

read_scrollback

读取 tmux 会话中的回滚历史。

参数：

• lines（数字）：从回滚缓冲区中获取的行数

示例：

{
  "name": "read_scrollback",
  "arguments": {
    "lines": 100
  }
}

get_terminal_info

获取终端信息（尺寸、当前路径等）。

示例：

{
  "name": "get_terminal_info"
}

可用资源

terminal://current

将当前终端内容作为文本资源提供。

terminal://info

终端元数据和信息。

工作原理

该服务会创建或连接到一个 tmux 会话，并使用 tmux 内置命令安全地读取终端内容：

1. 会话管理：创建或连接到一个分离的 tmux 会话
2. 内容捕获：使用 tmux capture-pane 读取可见内容
3. 只读：绝不会向会话发送按键或命令
4. MCP 协议：通过标准 MCP 工具和资源公开终端内容

这种方式确保 AI 助手能够观察终端活动，而不会有意外执行命令或修改终端状态的风险。

使用场景

• 监控长时间运行的进程和构建输出
• 观察基于终端的应用行为
• 查看终端历史记录以调试问题
• 根据当前终端状态提供上下文感知的帮助

安全注意事项

MCP SSH Wingman 在设计时充分考虑了安全性：

• 只读：该服务绝不会向终端发送输入
• 本地访问：仅对本地 tmux 会话进行操作
• 不执行命令：无法执行 shell 命令
• 会话隔离：每个会话相互独立，并由 tmux 进行沙盒隔离

故障排除

服务无法启动

• 确保已安装 tmux：tmux -V
• 检查二进制文件是否具有执行权限：chmod +x /usr/local/bin/mcp-ssh-wingman

Claude Desktop 无法连接

• 确认配置文件中的二进制文件路径正确
• 检查 Claude Desktop 日志中的错误消息
• 确保先从命令行成功运行该二进制文件

看不到终端内容

• 确认 tmux 会话存在：tmux list-sessions
• 确保会话名称与配置中指定的名称一致
• 检查 tmux 会话是否有活动窗格

参与贡献

欢迎贡献！请随时提交问题或拉取请求。

开发指南请参阅 DEVELOPMENT.md。