ssh

SSH MCP 服务

一个用于管理 SSH 远程服务的 MCP（Model Context Protocol）服务，支持 SSH Agent 身份验证。

此服务解决了 SSH MCP 服务中的一个常见问题：支持受密码短语保护的 SSH 密钥。通过使用 SSH Agent 身份验证，你可以安全地连接到远程服务，而无需暴露密钥密码短语。

亮点

• SSH Agent 身份验证 - 通过 SSH Agent 无缝使用受密码短语保护的 SSH 密钥
• 私钥文件支持 - 可通过直接使用私钥文件进行身份验证
• 启动健康检查 - 启动时验证 SSH 连接，并提供清晰的错误消息
• 命令执行 - 在远程服务上运行 shell 命令
• 文件传输 - 通过 SFTP 上传和下载文件
• 目录列表 - 浏览远程文件系统
• 工具组 - 控制可用的工具（readonly、write、admin）

身份验证优先级

此服务支持多种身份验证方式，并按以下顺序使用：

1. SSH Agent（推荐）- 如果已设置 SSH_AUTH_SOCK 或自动检测到该变量
2. 私钥文件 - 如果已设置 SSH_PRIVATE_KEY_PATH

两种方式可以同时配置。如果 SSH Agent 身份验证可用，则优先使用。私钥文件方式用作备用方式，或在 Agent 不可用时使用。

功能

工具

工具	分组	描述
ssh_connection_info	readonly, write, admin	获取已配置的 SSH 连接信息
ssh_list_directory	readonly, write, admin	列出远程服务上的目录内容
ssh_download	readonly, write, admin	通过 SFTP 从远程服务下载文件
ssh_upload	write, admin	通过 SFTP 上传文件到远程服务
ssh_execute	admin	在远程服务上执行 shell 命令

资源

资源	描述
ssh://config	SSH 连接配置和状态（用于调试）

工具组

通过 ENABLED_TOOLGROUPS 环境变量控制可用的工具：

分组	描述
readonly	安全操作（连接信息、列出目录、下载）
write	文件修改（上传）
admin	完全访问权限，包括命令执行

示例：

• ENABLED_TOOLGROUPS="readonly" - 仅允许浏览和下载
• ENABLED_TOOLGROUPS="readonly,write" - 允许文件传输，但不允许执行命令
• 未设置 - 启用所有工具（默认）

启动健康检查

此服务会在启动时执行 SSH 连接健康检查，以验证已配置的凭据和主机是否有效。这样可以立即发现配置问题，而不是等到工作流运行期间才发现。

优势：

• 更快获得反馈：配置错误会在启动时暴露，而不是在工作流进行到一半时才发现
• 更清晰的错误消息：启动失败时会提供常见问题的提示
• 改善用户体验：消除对服务运行状态的疑问

配置：

• SKIP_HEALTH_CHECKS=true - 跳过健康检查（适用于延迟建立连接的场景）
• HEALTH_CHECK_TIMEOUT=10000 - 自定义健康检查超时时间（默认：10 秒）

提供的错误提示：

• 身份验证失败（SSH 密钥未加载、密钥错误）
• 连接超时（无法访问主机）
• 连接被拒绝（SSH 服务未运行）
• DNS 解析错误（主机名无效）

快速开始

安装

npx ssh-agent-mcp-server

或全局安装：

npm install -g ssh-agent-mcp-server

配置

环境变量

变量	必填	描述	默认值
SSH_HOST	是	SSH 服务的主机名或 IP 地址	-
SSH_USERNAME	是	SSH 身份验证用户名	-
SSH_PORT	否	SSH 端口号	22
SSH_AUTH_SOCK	否	SSH Agent 套接字的路径	自动检测
SSH_PRIVATE_KEY_PATH	否	私钥文件的路径	-
SSH_PASSPHRASE	否	加密私钥的密码短语	-
SSH_TIMEOUT	否	连接超时时间（毫秒）	30000
SSH_COMMAND_TIMEOUT	否	默认命令活动超时时间（毫秒）	60000
ENABLED_TOOLGROUPS	否	以逗号分隔的工具组	全部启用
SKIP_HEALTH_CHECKS	否	启动时跳过 SSH 连接健康检查	false
HEALTH_CHECK_TIMEOUT	否	健康检查超时时间（毫秒）	10000

Claude Desktop 配置

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

Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "ssh-agent-mcp-server"],
      "env": {
        "SSH_HOST": "192.168.1.100",
        "SSH_USERNAME": "deploy",
        "SSH_AUTH_SOCK": "${SSH_AUTH_SOCK}"
      }
    }
  }
}

重启 Claude Desktop，即可开始使用！

SSH Agent 身份验证（推荐）

对于受密码短语保护的密钥，推荐使用 SSH Agent 身份验证：

1. 确保 SSH Agent 正在运行，且已加载你的密钥：

   # Check if agent is running
   ssh-add -l
   
   # If not, add your key
   ssh-add ~/.ssh/id_ed25519
   

2. 将 SSH_AUTH_SOCK 环境变量传递给 MCP 服务

服务会自动使用 Agent 进行身份验证，你受密码短语保护的密钥会安全地保存在 Agent 中。

工作原理

1. 通过 ssh-add 将受密码短语保护的密钥加载到 SSH Agent
2. Agent 会在 $SSH_AUTH_SOCK 处提供一个 Unix 套接字
3. 此 MCP 服务通过 ssh2 库连接到该套接字
4. Agent 使用解密后的密钥对身份验证质询进行签名
5. 私钥始终保留在 Agent 中，不会离开；MCP 服务永远不会看到它

这比以下方式更安全：

• 将密码短语存储在环境变量中
• 使用未受保护的私钥
• 手动输入密码短语

工具详情

ssh_execute

在远程服务上执行命令。

参数：

• command（必填）：要执行的 Shell 命令
• cwd（可选）：工作目录
• timeout（可选）：活动超时时间（毫秒；默认值：60000 或 SSH_COMMAND_TIMEOUT）

基于活动的超时：

超时基于活动，而不是绝对时长。每当收到命令的 stdout 或 stderr 输出时，计时器都会重置。这样一来，能够定期产生输出的长时间运行命令（例如构建、部署或 claude -p 命令）可以顺利完成，同时没有任何活动、陷入停滞的命令仍会超时。

对于初始输出延迟较长的命令（在输出任何内容前延迟 10-30 秒或更久），你可以：

1. 通过 SSH_COMMAND_TIMEOUT 环境变量延长默认超时时间
2. 为特定命令传入更高的 timeout 参数

示例：

{
  "command": "ls -la /var/log",
  "cwd": "/home/user"
}

长时间运行命令的延长超时示例：

{
  "command": "npm run build",
  "timeout": 300000
}

**返回：**包含 stdout、stderr 和退出代码的 JSON

ssh_upload

通过 SFTP 将文件上传到远程服务。

参数：

• localPath（必填）：本地文件的绝对路径
• remotePath（必填）：服务上的目标路径

ssh_download

通过 SFTP 从远程服务下载文件。

参数：

• remotePath（必填）：远程服务上的路径
• localPath（必填）：本地目标路径

ssh_list_directory

列出远程服务上的目录内容。

参数：

• path（必需）：要列出的目录路径

**返回：**包含文件名、类型、大小、权限和修改时间的 JSON 数组

ssh_connection_info

获取已配置的 SSH 连接信息。

**返回：**包含主机、端口、用户名和身份验证详情的 JSON

开发

# Install dependencies
npm run install-all

# Build
npm run build

# Run in development mode
npm run dev

# Run tests
npm test
npm run test:integration

许可证

MIT