JinDaGe - ssh-client-mcp MCP Details

article

README

🚀 SSH/SFTP MCP 服务器

SSH/SFTP MCP 服务器是一个基于模型上下文协议（MCP）的服务器，它允许像 Claude 这样的 AI 助手在远程服务器上执行 SSH 命令并进行 SFTP 文件操作。

🚀 快速开始

配置 Claude 桌面版

将以下配置添加到你的 Claude 桌面版配置文件中：

Windows：%APPDATA%\Claude\claude_desktop_config.json
macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

选项 1：命令行参数（推荐）

通过命令行参数直接配置服务器：

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": [
        "ssh-client-mcp",
        "--host", "192.168.1.100",
        "--user", "admin",
        "--password", "your-password"
      ]
    }
  }
}

使用私钥认证：

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": [
        "ssh-client-mcp",
        "--host", "192.168.1.100",
        "--user", "admin",
        "--key", "~/.ssh/id_rsa"
      ]
    }
  }
}

使用私钥 + 密码短语：

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": [
        "ssh-client-mcp",
        "--host", "192.168.1.100",
        "--user", "admin",
        "--key", "~/.ssh/id_rsa",
        "--passphrase", "your-key-passphrase"
      ]
    }
  }
}

可用的命令行参数：

| 参数 | 短参数 | 描述 | |------|-------|-------------| | --host | -h | 服务器主机名或 IP | | --port | -p | SSH 端口（默认：22） | | --user | -u | SSH 用户名 | | --password | | SSH 密码 | | --key | -k | 私钥文件路径 | | --passphrase | | 私钥密码短语 | | --id | | 服务器 ID（默认："cli"） | | --name | | 服务器显示名称 |

选项 2：配置文件

在工作目录中创建一个 servers.json 文件：

{
  "servers": [
    {
      "id": "my-server",
      "name": "My Server",
      "host": "192.168.1.100",
      "port": 22,
      "username": "admin",
      "password": "your-password"
    }
  ],
  "defaultServer": "my-server"
}

选项 3：环境变量

SSH_SERVER_DEV_HOST=192.168.1.100
SSH_SERVER_DEV_PORT=22
SSH_SERVER_DEV_USERNAME=admin
SSH_SERVER_DEV_PASSWORD=your-password
SSH_SERVER_DEV_NAME=Development Server

然后重启 Claude 桌面版以加载 MCP 服务器。

✨ 主要特性

服务器配置管理：可以在配置文件或环境变量中定义服务器。
连接测试：在建立会话之前测试服务器连接性。
SSH 命令执行：远程运行命令，支持可选的 sudo 权限。
SFTP 文件操作：可以上传、下载、列出、创建和删除文件/目录。
会话管理：自动清理空闲会话，支持连接池。
多种认证方法：支持密码和私钥认证。

📦 安装指南

使用 npx（推荐）

npx ssh-client-mcp

使用 npm

npm install -g ssh-client-mcp

从源代码安装

git clone https://github.com/veithly/ssh-client-mcp.git
cd ssh-client-mcp
npm install
npm run build

💻 使用示例

列出已配置的服务器

Tool: ssh_list_servers
Arguments: {}

测试连接

Tool: ssh_test_connection
Arguments: {
  "serverId": "my-server"
}

连接到服务器

Tool: ssh_connect_by_id
Arguments: {
  "serverId": "my-server"
}

执行命令

Tool: ssh_exec
Arguments: {
  "sessionId": "<session-id>",
  "command": "ls -la /home"
}

上传文件

Tool: sftp_upload
Arguments: {
  "sessionId": "<session-id>",
  "localPath": "/local/path/file.txt",
  "remotePath": "/remote/path/file.txt"
}

下载文件

Tool: sftp_download
Arguments: {
  "sessionId": "<session-id>",
  "remotePath": "/remote/path/file.txt",
  "localPath": "/local/path/file.txt"
}

📚 详细文档

可用工具（共 18 个）

服务器管理

| 工具 | 描述 | |------|-------------| | ssh_list_servers | 列出所有已配置的服务器 | | ssh_get_server | 获取特定服务器的详细信息 | | ssh_test_connection | 测试与服务器的连接 | | ssh_test_all_connections | 测试所有已配置的服务器 | | ssh_connect_by_id | 使用配置中的服务器 ID 进行连接 |

连接管理

| 工具 | 描述 | |------|-------------| | ssh_connect | 使用凭据建立 SSH 连接 | | ssh_disconnect | 关闭 SSH 会话 | | ssh_list_sessions | 列出所有活动的 SSH 会话 |

命令执行

| 工具 | 描述 | |------|-------------| | ssh_exec | 在远程服务器上执行命令 | | ssh_sudo_exec | 使用 sudo 权限执行命令 |

文件操作（SFTP）

| 工具 | 描述 | |------|-------------| | sftp_upload | 将本地文件上传到远程服务器 | | sftp_download | 从远程服务器下载文件 | | sftp_ls | 列出远程目录的内容 | | sftp_mkdir | 在远程服务器上创建目录 | | sftp_rm | 删除文件或目录 | | sftp_stat | 获取文件/目录信息 | | sftp_read | 读取远程文件的内容 | | sftp_write | 将内容写入远程文件 |

配置选项

环境变量

| 变量 | 描述 | 默认值 | |----------|-------------|---------| | SESSION_TIMEOUT | 会话超时时间（毫秒） | 1800000（30 分钟） | | MAX_SESSIONS | 最大并发会话数 | 100 | | SSH_CONNECTION_TIMEOUT | 连接超时时间（毫秒） | 30000 | | SSH_DEFAULT_SERVER | 默认服务器 ID | - |

服务器配置字段

| 字段 | 类型 | 是否必需 | 描述 | |-------|------|----------|-------------| | id | 字符串 | 是 | 唯一的服务器标识符 | | name | 字符串 | 是 | 显示名称 | | host | 字符串 | 是 | 主机名或 IP 地址 | | port | 数字 | 否 | SSH 端口（默认：22） | | username | 字符串 | 是 | SSH 用户名 | | password | 字符串 | 否* | SSH 密码 | | privateKeyPath | 字符串 | 否* | 私钥文件路径 | | passphrase | 字符串 | 否 | 私钥密码短语 | | description | 字符串 | 否 | 服务器描述 | | tags | 字符串数组 | 否 | 用于过滤的标签 |

*必须提供 password 或 privateKeyPath 中的一个。

安全注意事项

会话在 30 分钟无活动后自动过期。
最大会话限制可防止资源耗尽。
凭据不会持久存储。
sudo 密码不会被记录。
尽可能使用 SSH 密钥代替密码。

开发

# 克隆仓库
git clone https://github.com/veithly/ssh-client-mcp.git
cd ssh-client-mcp

# 安装依赖
npm install

# 构建
npm run build

# 监听模式
npm run dev

# 清理构建
npm run clean

项目结构

ssh-client-mcp/
├── src/
│   ├── index.ts              # MCP 服务器入口点
│   ├── types.ts              # 类型定义
│   ├── SessionManager.ts     # SSH 会话生命周期管理
│   ├── SSHExecutor.ts        # 命令执行
│   ├── SFTPOperations.ts     # SFTP 文件操作
│   ├── ConnectionTester.ts   # 连接测试
│   ├── config/
│   │   ├── ConfigManager.ts  # 配置管理
│   │   ├── types.ts          # 配置类型
│   │   └── index.ts          # 配置导出
│   └── tools/
│       ├── connection.ts     # 连接工具
│       ├── command.ts        # 命令工具
│       ├── file.ts           # 文件工具
│       ├── server.ts         # 服务器管理工具
│       └── index.ts          # 工具导出
├── servers.example.json      # 示例服务器配置
├── .env.example              # 示例环境配置
├── package.json
├── tsconfig.json
└── README.md

贡献

欢迎贡献代码！请随时提交拉取请求。

分叉仓库。
创建你的功能分支 (git checkout -b feature/AmazingFeature)。
提交你的更改 (git commit -m 'Add some AmazingFeature')。
推送到分支 (git push origin feature/AmazingFeature)。
打开拉取请求。

📄 许可证

致谢

模型上下文协议 - MCP SDK
ssh2 - 用于 Node.js 的 SSH2 客户端库

专为 Claude AI 设计

ssh-client-mcp