SSH MCP Server

面向 AI 助手的 SSH MCP 服务——安全的远程服务管理

一个安全、可用于生产环境的 Model Context Protocol（MCP） 服务，可让 AI 助手通过 SSH 管理远程基础设施。

SSH MCP 服务在大语言模型（LLM）与您的基础设施之间搭建桥梁。它让 Claude Desktop、Cursor 和 GitHub Copilot 等 AI 助手能够安全地执行命令、通过 SFTP 传输文件，以及管理端口转发隧道。将您的 AI 打造成一名能力出众的 DevOps 助手，在严格的安全边界内排查故障、部署应用并监控服务器。

目录

• 为什么使用 SSH MCP 服务？
• 兼容性
• 功能
• 安装
• 快速入门
• 配置
• 可用工具
• 安全性
• 示例
• 许可证

为什么使用 SSH MCP 服务？

• DevOps 自动化：让您的 AI 助手检查 Docker 容器状态、读取 Kubernetes Pod 日志，或重启 systemd 服务。
• 基础设施调试：使用自然语言快速分析日志文件、检查磁盘使用情况并排查网络问题。
• 安全的文件管理：无需离开聊天界面，即可通过 SFTP 安全地读取配置文件、更新脚本或获取日志。
• 复杂工作流：通过一个提示词串联多个命令和工具，执行复杂的维护任务。

兼容性

此 MCP 服务专为兼容 Model Context Protocol 的客户端设计，包括：

• Anthropic Claude Desktop
• Cursor Editor
• GitHub Copilot

功能

• 🔐 安全的 SSH 命令执行 - 在远程服务上运行 Shell 命令，并进行严格验证和超时控制。
• 🛡️ 精细化访问控制 - 将特定命令及参数列入允许列表，防止未经授权的操作（例如，允许 docker ps，但禁止 docker stop）。
• 📁 SFTP 集成 - 全面支持在远程文件系统上读取、写入和列出文件。
• 🌉 智能端口转发 - 自动管理 SSH 隧道，以访问数据库或仪表板等内部服务。
• 🔄 稳健的连接池 - 高效管理多个持久 SSH 连接，提升性能。
• 🔑 基于密钥的身份验证 - 支持标准 SSH 密钥（Ed25519、RSA），实现安全的无密码身份验证。
• ⚙️ 导入 SSH 配置 - 无缝导入现有 ~/.ssh/config 文件中的主机。
• 🎯 参数化模板 - 为常见任务定义安全、可复用的命令模板（宏）。
• 📝 审计日志 - 为所有已执行的命令生成完整的 JSONL 审计记录，便于合规检查和安全审查。

安装

作为 MCP 服务

推荐的使用方式是将此软件包用作 MCP 服务，配合 GitHub Copilot 等 AI 助手使用。

前提条件：

• Node.js 18.0.0 或更高版本
• 可通过 SSH 访问目标服务器
• 已配置 SSH 私钥

使用 npx（推荐）：

无需安装！将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": [
        "@uarlouski/ssh-mcp-server@latest",
        "--configPath=/path/to/your/ssh-mcp-config.json"
      ]
    }
  }
}

全局安装：

npm install -g @uarlouski/ssh-mcp-server

然后进行如下配置：

{
  "mcpServers": {
    "ssh": {
      "command": "ssh-mcp-server",
      "args": ["--configPath=/path/to/your/ssh-mcp-config.json"]
    }
  }
}

快速开始

1. 创建 SSH 密钥

如果还没有用于服务器的 SSH 密钥：

ssh-keygen -t ed25519 -f ~/.ssh/deploy_key -C "[email protected]"
ssh-copy-id -i ~/.ssh/deploy_key.pub [email protected]

2. 创建配置文件

创建一个 ssh-mcp-config.json 文件：

{
  "allowedCommands": ["ls", "cat", "grep", "docker", "kubectl"],
  "servers": {
    "my-server": {
      "host": "example.com",
      "username": "deploy",
      "privateKeyPath": "~/.ssh/deploy_key"
    }
  }
}

3. 配置 MCP 客户端

将服务添加到 MCP 客户端（例如 GitHub Copilot）：

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": [
        "@uarlouski/ssh-mcp-server@latest",
        "--configPath=/Users/yourname/ssh-mcp-config.json"
      ]
    }
  }
}

4. 重启 MCP 客户端

重启 AI 助手以加载新的服务配置。

配置

基本配置

配置文件支持以下选项：

{
  "allowedCommands": ["ls", "pwd", "cat", "grep", "docker", "kubectl"],
  "servers": {
    "server-name": {
      "host": "hostname-or-ip",
      "port": 22,
      "username": "username",
      "privateKeyPath": "~/.ssh/private_key"
    }
  },
  "portForwardingServices": {
    "service-name": {
      "connectionName": "server-name",
      "localPort": 8080,
      "remoteHost": "localhost",
      "remotePort": 80,
      "description": "Optional description"
    }
  },
  "commandTemplates": {
    "k8s-pod-logs": {
      "command": "kubectl logs -n {{namespace}} {{pod}} --tail={{lines:100}}",
      "description": "Fetch Kubernetes pod logs with configurable tail size"
    },
    "app-deploy": {
      "command": "cd /var/www/{{app}} && git pull origin {{branch:main}} && npm install && pm2 restart {{app}}",
      "description": "Deploy application with git pull, npm install, and pm2 restart"
    },
    "docker-stats": "docker stats {{container:--all}} --no-stream --format 'table {{.Name}}\\t{{.CPUPerc}}'"
  },
  "commandTimeout": 30000,
  "maxConnections": 10
}

配置选项

allowedCommands（可选）

允许执行的基础命令名称数组。

• 如果指定（非空）：启用严格验证
  • 只能执行列表中的命令
  • 验证包含管道符（|）、命令链（&&、||、;）和命令替换（$()）的复杂命令
  • 阻止绕过验证的尝试，例如 ls | rm -rf /
• 如果省略或为空：禁用验证（允许所有命令，请谨慎使用！）

示例：

"allowedCommands": ["ls", "cat", "grep", "docker", "kubectl", "systemctl"]

servers（必填）

具名 SSH 服务配置。每个服务必须包含：

• host（必填）：主机名或 IP 地址
• username（必填）：SSH 用户名
• privateKeyPath（必填）：SSH 私钥路径（支持 ~ 展开）
• port（可选）：SSH 端口（默认值：22）

示例：

"servers": {
  "staging-api": {
    "host": "api-staging-01.example.com",
    "username": "deploy",
    "privateKeyPath": "~/.ssh/staging_deploy_key"
  },
  "staging-db": {
    "host": "db-staging-master.example.com",
    "port": 2222,
    "username": "dbadmin",
    "privateKeyPath": "~/.ssh/db_admin_key"
  }
}

sshConfigImport（可选）

从现有 SSH 配置文件（例如 ~/.ssh/config）导入服务配置。此功能可让你重复使用现有 SSH 配置，无需在 MCP 配置文件中重复定义。

优点：

• 🔄 重复使用现有 SSH 配置
• 🎯 使用模式匹配导入指定主机
• 🔒 跨平台运行（macOS、Linux、Windows）

配置：

• path（字符串，可选）：SSH 配置文件路径（默认值：~/.ssh/config）
• hosts（字符串数组，可选）：要导入的主机模式（例如，["prod-*", "staging-*"]）
  • 支持通配符：*（匹配任意字符）、?（匹配单个字符）
  • 如果省略，则导入所有有效主机（不包括仅包含通配符的主机，例如 *）

**注意：**只需在配置中定义 sshConfigImport 即可启用 SSH 配置导入。如需禁用，请完全移除 sshConfigImport 字段。

示例——使用模式匹配导入指定主机：

{
  "sshConfigImport": {
    "path": "/custom/path/to/ssh_config",
    "hosts": ["prod-*", "staging-*"]
  }
}

注意事项：

• 仅导入包含所有必填字段（HostName、User、IdentityFile）的主机
• 通配符 SSH 配置项（Host *）会将其设置应用于指定主机，但不会作为独立服务导入
• 如果 SSH 配置文件不存在，服务将继续使用手动定义的服务
• **重要：**如果手动配置和 SSH 配置导入中存在同名服务，服务将无法启动，并显示明确的错误信息。请使用 hosts 模式筛选器避免冲突，或在其中一个配置中重命名服务。

portForwardingServices（可选）

为常见用例预先配置的具名端口转发服务。

• connectionName（必填）：servers 配置中的服务器名称
• remoteHost（必填）：要转发到的远程主机
• remotePort（必填）：要转发到的远程端口
• localPort（可选）：要绑定的本地端口（省略时随机分配）
• description（可选）：易于理解的描述

示例：

"portForwardingServices": {
  "pg-staging-database": {
    "connectionName": "staging-db",
    "remoteHost": "db-internal-01.example.com",
    "remotePort": 5432,
    "description": "PostgreSQL database access"
  }
}

commandTemplates（可选）

可复用的参数化命令模板，支持变量替换。

模板可通过以下两种格式定义：

• 字符串格式："template-name": "command with {{variables}}"
• 对象格式："template-name": { "command": "...", "description": "..." }

变量语法：

• {{variable}} - 必填变量
• {{variable:default}} - 带默认值的可选变量
• {{.field}} - 为 Docker/Go 模板保留（不会进行替换）

示例：

"commandTemplates": {
  "k8s-pod-logs": {
    "command": "kubectl logs -n {{namespace}} {{pod}} --tail={{lines:100}}",
    "description": "Fetch Kubernetes pod logs with configurable tail size"
  },
  "app-deploy": {
    "command": "cd /var/www/{{app}} && git pull origin {{branch:main}} && npm install && pm2 restart {{app}}",
    "description": "Deploy application"
  },
  "docker-stats": "docker stats {{container:--all}} --no-stream --format 'table {{.Name}}\\t{{.CPUPerc}}'",
  "nginx-reload": "sudo nginx -t && sudo systemctl reload nginx"
}

与 AI 配合使用：

"Get logs from the api-7d8f9 pod in the staging namespace"

AI 会识别出这与 k8s-pod-logs 模板匹配，并使用相应变量执行该模板。

commandTimeout（可选）

命令执行超时时间，单位为毫秒。默认值：30000（30 秒）。

maxConnections（可选）

最大并发 SSH 连接数。默认值：5。

auditLog（可选）

配置 SSH 会话的审计日志记录。

• enabled（布尔值，可选）：启用审计日志记录（默认值：false）
• folder（字符串，可选）：审计日志的存储路径（默认为当前目录）

示例：

"auditLog": {
  "enabled": true,
  "folder": "~/ssh-audit-logs"
}

完整示例

完整配置示例请参见 config.example.json。

可用工具

ssh_execute_command

在远程服务上执行命令。

参数：

• connectionName（字符串，必填）：配置中服务器的名称
• command（字符串，必填）：要执行的命令
• commandTimeout（数字，可选）：命令执行超时时间，单位为毫秒（覆盖全局 commandTimeout）

示例：

{
  "connectionName": "staging-api",
  "command": "docker ps -a"
}

响应：

{
  "stdout": "CONTAINER ID   IMAGE     COMMAND   ...",
  "stderr": "",
  "exitCode": 0,
  "timedOut": false
}

此工具可帮助 AI 助手了解哪些服务器可用于 SSH 操作，而无需查看完整的配置文件。

ssh_list_servers

列出配置文件中配置的所有可用 SSH 服务器。

**参数：**无

示例：

{}

响应：

{
  "success": true,
  "servers": [
    {
      "name": "production-api",
      "host": "api-prod-01.example.com",
      "port": 22,
      "username": "deploy"
    },
    {
      "name": "staging-db",
      "host": "db-staging.example.com",
      "port": 2222,
      "username": "admin"
    }
  ],
  "count": 2
}

此工具可帮助 AI 助手发现有哪些服务器可用于 SSH 操作，而无需查看完整的配置文件。

ssh_port_forward

设置 SSH 端口转发，以访问远程服务。

参数：

• connectionName（字符串，必填）：配置中服务器的名称
• remoteHost（字符串，必填）：要转发到的远程主机
• remotePort（数字，必填）：要转发到的远程端口
• localPort（数字，可选）：要绑定的本地端口（省略时随机分配）

指定本地端口的示例：

{
  "connectionName": "staging-db",
  "localPort": 8080,
  "remoteHost": "internal-db.cluster.local",
  "remotePort": 5432
}

自动分配端口的示例：

{
  "connectionName": "staging-db",
  "remoteHost": "internal-db.cluster.local",
  "remotePort": 5432
}

响应：

{
  "id": "a1b2c3d4",
  "localPort": 8080,
  "remoteHost": "internal-db.cluster.local",
  "remotePort": 5432,
  "status": "active"
}

ssh_close_port_forward

关闭活动端口转发。

参数：

• id（字符串，必填）：要关闭的活动端口转发的唯一 ID

示例：

{
  "id": "a1b2c3d4"
}

ssh_restart_port_forward

使用唯一 ID 重启活动端口转发。

参数：

• id（字符串，必填）：要重启的活动端口转发的唯一 ID

示例：

{
  "id": "a1b2c3d4"
}

ssh_list_port_forwards

列出所有连接中的活动端口转发。

**参数：**无

响应：

{
  "forwards": [
    {
      "id": "a1b2c3d4",
      "sshConnection": "[email protected]:2222",
      "tunnel": "localhost:8080 -> internal-db.cluster.local:5432",
      "status": "active"
    }
  ]
}

ssh_port_forward_service

从配置中启动预配置的命名端口转发服务。

参数：

• serviceName（字符串，必填）：portForwardingServices 配置中的服务名称

示例：

{
  "serviceName": "pg-staging-database"
}

这相当于使用预配置参数调用 ssh_port_forward（返回结果会包含生成的唯一 id）。

ssh_upload_file

通过 SFTP 将本地系统中的文件上传到远程服务。

参数：

• connectionName（字符串，必填）：配置中服务器的名称
• localPath（字符串，必填）：要上传的本地文件路径
• remotePath（字符串，必填）：远程目标路径
• permissions（字符串，可选）：八进制格式的文件权限（例如 "0644"、"0755"）

示例：

{
  "connectionName": "app-server",
  "localPath": "~/configs/app.json",
  "remotePath": "/var/www/app/config.json",
  "permissions": "0644"
}

响应：

{
  "success": true,
  "bytesTransferred": 1024,
  "message": "Successfully uploaded ~/configs/app.json to /var/www/app/config.json",
  "localPath": "~/configs/app.json",
  "remotePath": "/var/www/app/config.json"
}

ssh_download_file

通过 SFTP 将文件从远程服务下载到本地系统。

参数：

• connectionName (string，必填)：配置中的服务名称
• remotePath (string，必填)：要下载的远程文件路径
• localPath (string，必填)：本地目标路径

示例：

{
  "connectionName": "app-server",
  "remotePath": "/var/log/app/error.log",
  "localPath": "~/downloads/error.log"
}

响应：

{
  "success": true,
  "bytesTransferred": 2048,
  "message": "Successfully downloaded /var/log/app/error.log to ~/downloads/error.log",
  "remotePath": "/var/log/app/error.log",
  "localPath": "~/downloads/error.log"
}

ssh_list_remote_files

通过 SFTP 列出远程目录中的文件。

参数：

• connectionName (string，必填)：配置中的服务名称
• remotePath (string，必填)：要列出的远程目录路径
• pattern (string，可选)：用于筛选文件的 Glob 模式（例如，".log"、".json"）

示例：

{
  "connectionName": "app-server",
  "remotePath": "/var/log/app",
  "pattern": ".*\\.log$"
}

响应：

{
  "remotePath": "/var/log/app",
  "pattern": ".*\\.log$",
  "totalCount": 3,
  "files": [
    {
      "name": "error.log",
      "size": 10485760,
      "modified": "2024-12-04T12:00:00.000Z",
      "permissions": "100644",
      "isDirectory": false,
      "isFile": true
    }
  ]
}

ssh_delete_remote_file

通过 SFTP 删除远程服务上的文件。

参数：

• connectionName (string，必填)：配置中的服务名称
• remotePath (string，必填)：要删除的远程文件路径

示例：

{
  "connectionName": "app-server",
  "remotePath": "/tmp/old-backup.tar.gz"
}

响应：

{
  "success": true,
  "message": "Successfully deleted /tmp/old-backup.tar.gz",
  "remotePath": "/tmp/old-backup.tar.gz"
}

ssh_execute_template

执行预配置的命令模板，并替换变量。

参数：

• connectionName (string，必填)：配置中的服务名称
• templateName (string，必填)：命令模板名称
• variables (object，可选)：用于替换变量的键值对
• commandTimeout (number，可选)：命令执行超时时间，单位为毫秒（覆盖全局 commandTimeout）

示例：

{
  "connectionName": "kubernetes-bastion",
  "templateName": "k8s-pod-logs",
  "variables": {
    "namespace": "staging",
    "pod": "api-7d8f9",
    "lines": "50"
  }
}

响应：

{
  "success": true,
  "templateName": "k8s-pod-logs",
  "expandedCommand": "kubectl logs -n production api-7d8f9 --tail=50",
  "variables": {
    "namespace": "staging",
    "pod": "api-7d8f9",
    "lines": "50"
  },
  "result": {
    "stdout": "...",
    "stderr": "",
    "exitCode": 0,
    "timedOut": false
  }
}

ssh_list_templates

列出所有可用的命令模板及其描述和变量。

参数： 无

示例：

{}

响应：

{
  "success": true,
  "templates": [
    {
      "name": "k8s-pod-logs",
      "command": "kubectl logs -n {{namespace}} {{pod}} --tail={{lines:100}}",
      "description": "Fetch Kubernetes pod logs with configurable tail size",
      "variables": [
        { "name": "namespace", "required": true },
        { "name": "pod", "required": true },
        { "name": "lines", "required": false, "defaultValue": "100" }
      ]
    }
  ],
  "count": 1
}

安全性

内置安全功能

1. 命令验证

   • 指定 allowedCommands 后会自动启用
   • 验证所有命令，包括管道（|）、链式命令（&&、||、;）和命令替换（$()、反引号）
   • 阻止 ls | rm -rf / 或 cat $(whoami) 等绕过尝试
   • 使用稳健的解析方式，防止命令注入

2. 服务允许列表

   • 只能访问 ssh-mcp-config.json 中预配置的服务
   • 不允许动态连接服务
   • 防止未经授权访问基础设施

3. 仅支持 SSH 密钥认证

   • 仅支持基于 SSH 密钥的认证
   • 不支持密码认证
   • 遵循安全最佳实践

4. 连接池

   • 通过 maxConnections 限制并发连接数
   • 防止资源耗尽
   • 自动清理空闲连接

5. 模板验证

   • 在加载配置时验证命令模板
   • 展开的模板命令也必须通过 allowedCommands 验证
   • 模板语法可避免与 Shell 变量替换冲突
   • Docker/Go 模板模式（{{.Field}}）会保留，不会被替换

安全注意事项

⚠️ 警告： 此服务提供强大的功能。请考虑以下事项：

• AI 助手可以在已配置的服务上执行命令并创建隧道
• 请确保了解授予的功能权限
• 从严格限制的 allowedCommands 开始，并按需放宽
• 为 MCP 访问使用单独的 SSH 密钥
• 定期审查命令执行日志

示例

示例 1：Kubernetes 管理

配置：

{
  "allowedCommands": ["kubectl", "helm", "docker"],
  "servers": {
    "k8s-bastion": {
      "host": "k8s-bastion.example.com",
      "username": "k8s-operator",
      "privateKeyPath": "~/.ssh/kubernetes_operator_key"
    }
  }
}

用法： 向 AI 助手询问：“检查 staging 命名空间中的 Pod 状态”

助手将执行：

{
  "connectionName": "k8s-bastion",
  "command": "kubectl get pods -n staging"
}

示例 2：通过端口转发访问数据库

配置：

{
  "servers": {
    "db-bastion": {
      "host": "bastion.example.com",
      "username": "dbadmin",
      "privateKeyPath": "~/.ssh/db_key"
    }
  },
  "portForwardingServices": {
    "staging-db": {
      "connectionName": "db-bastion",
      "localPort": 5432,
      "remoteHost": "db-internal.example.com",
      "remotePort": 5432,
      "description": "Staging PostgreSQL database"
    }
  }
}

用法： 向 AI 助手询问：“启动 staging 数据库隧道”

助手将执行：

{
  "serviceName": "staging-db"
}

然后，你可以在本地连接：psql -h localhost -p 5432 -U dbuser

示例 3：Docker 容器管理

配置：

{
  "allowedCommands": ["docker", "docker-compose"],
  "servers": {
    "app-server": {
      "host": "app-01.example.com",
      "username": "deploy",
      "privateKeyPath": "~/.ssh/deploy_key"
    }
  }
}

用法： 向 AI 助手询问：“在 app-server 上重启 nginx 容器”

助手将执行：

{
  "connectionName": "app-server",
  "command": "docker restart nginx"
}

示例 4：文件管理与日志分析

配置：

{
  "servers": {
    "app-server": {
      "host": "app-01.example.com",
      "username": "deploy",
      "privateKeyPath": "~/.ssh/deploy_key"
    }
  }
}

用法：

上传配置文件：

Ask your AI assistant: "Upload my local config.json to /var/www/app/config.json on app-server with 644 permissions"

助手将执行：

{
  "connectionName": "app-server",
  "localPath": "~/config.json",
  "remotePath": "/var/www/app/config.json",
  "permissions": "0644"
}

下载日志以进行分析：

Ask your AI assistant: "Download the error log from /var/log/app/error.log on app-server"

助手将执行：

{
  "connectionName": "app-server",
  "remotePath": "/var/log/app/error.log",
  "localPath": "~/downloads/error.log"
}

列出并筛选日志文件：

Ask your AI assistant: "Show me all .log files in /var/log/app on app-server"

助手将执行：

{
  "connectionName": "app-server",
  "remotePath": "/var/log/app",
  "pattern": ".*\\.log$"
}

清理旧备份：

Ask your AI assistant: "Delete the old backup at /tmp/backup-2024-01-01.tar.gz on app-server"

助手将执行：

{
  "connectionName": "app-server",
  "remotePath": "/tmp/backup-2024-01-01.tar.gz"
}

许可证

Apache 2.0 - 详情请参阅 LICENSE 文件。

---

代码仓库： github.com/uarlouski/ssh-mcp-server

问题反馈： github.com/uarlouski/ssh-mcp-server/issues

npm 软件包： @uarlouski/ssh-mcp-server