my-mcp-ssh

my-mcp-ssh

基于模型上下文协议（MCP）的 SSH 连接工具，允许大模型通过 SSH 安全地连接到远程服务，并通过 MCP 协议执行文件操作。

功能

• SSH 连接管理：连接到远程 SSH 服务
• 命令执行：在远程服务上执行命令
• 文件传输：上传和下载文件
• 会话管理：维护并关闭 SSH 会话

安装

依赖项

• Python >= 3.12
• uv 包管理器

# Clone the project
git clone https://github.com/ffpy/my-mcp-ssh.git

# Enter the project directory
cd my-mcp-ssh

# Install dependencies
uv sync

使用方法

在客户端中配置

{
  "mcpServers": {
    "my-mcp-ssh": {
      "command": "uv",
      "args": [
        "--directory",
        "<your_path>/my-mcp-ssh",
        "run",
        "src/main.py"
      ],
      "env": {}
    }
  }
}

环境变量

SSH 连接默认值（可选）

环境变量可为 SSH 连接提供默认值，适用于经常连接到同一服务或自动化环境：

• SSH_HOST：SSH 服务主机名或 IP 地址
• SSH_PORT：SSH 服务端口
• SSH_USERNAME：SSH 用户名
• SSH_PASSWORD：SSH 密码（使用密码认证时）
• SSH_KEY_PATH：SSH 私钥文件路径（使用密钥认证时）
• SSH_KEY_PASSPHRASE：SSH 私钥密码短语（如需要）

何时使用 SSH 环境变量：

• 重复连接：多次连接到同一服务时
• CI/CD 流水线：用于自动部署脚本
• 开发环境：为常用服务设置默认值
• 容器部署：无需修改代码即可配置默认值

注意：传递给 connect 工具的参数始终会覆盖环境变量。

服务配置

可以配置其他服务行为：

• SESSION_TIMEOUT：会话超时时间，单位为分钟，默认为 30 分钟
• MAX_OUTPUT_LENGTH：命令输出的最大字符数，默认为 5000 个字符

SSH 凭据文件

为提高安全性，你可以将 SSH 凭据存储在本地配置文件中，而不是将密码作为参数传递。

1. 复制示例文件：

cp ssh-credentials.json.example ssh-credentials.json

2. 使用实际凭据编辑 ssh-credentials.json：

{
  "[email protected]": "your_password",
  "admin@web-[0-9].example.com": "web_password",
  "deploy@server-{dev,test,staging}.company.com": "deploy_password",
  "admin@*.internal.network": "internal_password"
}

支持的模式：

• * - 匹配任意字符
• ? - 匹配单个字符
• [0-9] - 匹配任意数字
• {dev,test,staging} - 匹配所列选项中的任意一个

认证优先级：

1. 传递给 connect 工具的参数（password、key_path）
2. 凭据文件中的精确匹配项（username@host）
3. 凭据文件中的模式匹配项（通配符）
4. 环境变量密码（SSH_PASSWORD）
5. 环境变量密钥（SSH_KEY_PATH）
6. 默认 SSH 密钥（如果存在则使用 ~/.ssh/id_rsa）

安全性：

• 文件权限会自动设为 600（仅所有者可读写）
• 文件会添加到 .gitignore，以防意外提交

注意：

• 凭据文件变更会立即生效，无需重启服务
• 每次尝试连接时都会重新读取文件

工具列表

connect

连接到 SSH 服务

参数：

• host：SSH 服务主机名或 IP 地址（可选）
• port：SSH 服务端口（可选，默认值为 22）
• username：SSH 用户名（可选）
• password：用于身份验证的 SSH 密码（可选）
• key_path：用于身份验证的 SSH 私钥文件路径（可选）
• key_passphrase：如需要，提供 SSH 私钥密码短语（可选）

disconnect

断开 SSH 会话

参数：

• session_id：要断开的会话 ID

list_sessions

列出所有活动的 SSH 会话

参数：

• 无

execute

在 SSH 服务上执行命令

参数：

• session_id：会话 ID
• command：要执行的命令
• stdin：提供给命令的输入字符串，默认为空
• timeout：命令超时时间，单位为秒，默认为 60 秒

upload

将文件上传到 SSH 服务

参数：

• session_id：会话 ID
• local_path：本地文件路径
• remote_path：远程文件路径

下载

从 SSH 服务下载文件

参数：

• session_id：会话 ID
• remote_path：远程文件路径
• local_path：本地文件路径

调试

运行 ./inspector.sh 进行在线调试

许可证

my-mcp-ssh 根据 Apache License, Version 2.0 许可