使用说明

SSH MCP服务器

一种模型上下文协议（MCP）服务器，为Linux和Windows服务器提供安全的SSH控制。通过标准化的MCP接口执行远程shell命令、传输文件和管理多个服务器连接。

特性

多种身份验证方法：密码和SSH密钥身份验证
多跳SSH支持：通过多个跳跃主机/堡垒连接
文件操作：通过SFTP上传和下载文件
安全控制：命令白名单/黑名单配置
连接池：高效的连接管理和重用
TypeScript：完全类型安全和现代JavaScript功能
Bun运行时：快速执行和内置TypeScript支持

安装

先决条件

包子运行时已安装
Node.js 18+（为了兼容性）

快速入门（使用bunx）

无需安装即可直接运行：

# Generate example config file
bunx @frah/ssh-mcp --example-config > config.json

# Run with default config (./config.json)
bunx @frah/ssh-mcp

# Run with custom config file
bunx @frah/ssh-mcp --config /path/to/your/config.json

# Show help
bunx @frah/ssh-mcp --help

本地设置

克隆存储库：

git clone https://github.com/frah/ssh-mcp.git
cd ssh-mcp

安装依赖项：

bun install

复制并配置示例配置：

cp config.example.json config.json
# Edit config.json with your server details

配置

创建一个 config.json 基于所提供示例的文件：

{
  "connections": [
    {
      "id": "dev-server",
      "host": "192.168.1.100",
      "port": 22,
      "username": "developer",
      "password": "your-password",
      "description": "Development environment server",
      "commandWhitelist": ["^ls", "^cat", "^grep"],
      "timeout": 30000
    },
    {
      "id": "prod-server",
      "host": "prod.example.com",
      "username": "admin",
      "privateKeyPath": "/path/to/key",
      "commandBlacklist": ["^rm", "^dd"]
    }
  ],
  "globalSettings": {
    "maxConnections": 10,
    "defaultTimeout": 30000,
    "idleTimeout": 60000
  }
}

连接配置选项

id：连接的唯一标识符
host：服务器主机名或IP地址
port：SSH端口（默认值：22）
username：SSH用户名
password：密码验证（可选）
privateKey：私钥内容为字符串（可选）
privateKeyPath：私钥文件的路径（可选）
passphrase：私钥密码（可选）
description：连接的人类可读描述（可选）
proxy：多跳连接的代理配置数组
commandWhitelist：允许命令的正则表达式模式
commandBlacklist：被阻止命令的正则表达式模式
timeout：命令执行超时（毫秒）

全局设置选项

defaultTimeout：默认命令执行超时（毫秒）
maxConnections：并发SSH连接的最大数量
idleTimeout：SSH连接空闲超时（毫秒）（默认值：60000）
commandWhitelist：允许命令的全局正则表达式模式
commandBlacklist：被阻止命令的全局正则表达式模式

多跳SSH配置

对于通过堡垒主机的连接：

{
  "id": "internal-server",
  "host": "10.0.1.50",
  "username": "app-user",
  "privateKeyPath": "/path/to/key",
  "proxy": [
    {
      "host": "bastion.example.com",
      "username": "bastion-user",
      "privateKeyPath": "/path/to/bastion/key"
    }
  ]
}

用法

运行服务器

使用bunx（无需安装）

# Run with default config (./config.json)
bunx @frah/ssh-mcp

# Run with custom config file
bunx @frah/ssh-mcp --config /path/to/your/config.json

来源

启动MCP服务器（Bun原生支持TypeScript）：

bun run dev
# or directly
bun src/index.ts

生产建设

对于使用Node.js的生产部署：

bun run build
node dist/index.js

命令行选项

-c, --config <path>：指定配置文件的路径（默认值： ./config.json)
-h, --help：显示帮助消息
-v, --version：显示版本号
--example-config：将示例配置JSON输出到stdout

示例：

ssh-mcp                                    # Start with default config
ssh-mcp --config /etc/ssh-mcp/config.json # Use custom config path
ssh-mcp --example-config > config.json    # Generate config file
ssh-mcp --help                            # Show help information
ssh-mcp --version                         # Show version

可用的MCP工具

1.ssh_execute

在远程服务器上执行命令。

参数：

connectionId （string）：配置中的连接ID
command （string）：要执行的命令
timeout （数字，可选）：超时时间（毫秒）

例子：

{
  "tool": "ssh_execute",
  "arguments": {
    "connectionId": "dev-server",
    "command": "ls -la /var/log",
    "timeout": 5000
  }
}

2.ssh_upload

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

参数：

connectionId （string）：配置中的连接ID
localPath （string）：本地文件路径
remotePath （string）：远程目标路径

例子：

{
  "tool": "ssh_upload",
  "arguments": {
    "connectionId": "dev-server",
    "localPath": "/local/file.txt",
    "remotePath": "/remote/file.txt"
  }
}

3.ssh_download

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

参数：

connectionId （string）：配置中的连接ID
remotePath （string）：远程文件路径
localPath （string）：本地目标路径

例子：

{
  "tool": "ssh_download",
  "arguments": {
    "connectionId": "dev-server",
    "remotePath": "/remote/log.txt",
    "localPath": "/local/log.txt"
  }
}

4.ssh_list_servers

列出所有已配置的SSH服务器定义。

参数： 无

退货： 服务器配置数组，包括：

id：连接标识符
host：服务器主机名
port：SSH端口号
username：SSH用户名
description：人类可读的描述（如果已配置）

例子：

{
  "tool": "ssh_list_servers",
  "arguments": {}
}

响应示例：

[
  {
    "id": "dev-server",
    "host": "192.168.1.100",
    "port": 22,
    "username": "developer",
    "description": "Development environment server"
  },
  {
    "id": "prod-server",
    "host": "prod.example.com",
    "port": 22,
    "username": "admin",
    "description": ""
  }
]

安全功能

命令筛选

服务器支持命令的白名单和黑名单模式：

白名单：只允许使用与这些模式匹配的命令
黑名单：与这些模式匹配的命令被阻止
模式被评估为正则表达式
连接特定规则覆盖全局规则

内置危险指挥保护

以下危险命令始终被阻止：

rm -rf / 和变体
磁盘格式化命令
叉式炸弹
直接磁盘写入操作

路径消毒

所有文件路径都会自动清理，以防止目录遍历攻击。

Claude代码集成

要将此MCP服务器与Claude Code一起使用，请执行以下步骤：

1.配置克劳德代码

将MCP服务器添加到您的Claude Code配置文件中：

配置文件位置：

选项A：全局配置

Linux/macOS: ~/.claude.json
视窗: %USERPROFILE%\.claude.json

选项B：项目特定配置 创建 .claude/settings.local.json 在您的项目目录中。

配置示例：

使用bunx（推荐-无需安装）：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "bunx",
      "args": ["@frah/ssh-mcp", "--config", "/absolute/path/to/your/config.json"]
    }
  }
}

使用本地安装：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/ssh-mcp/src/index.ts", "--config", "/absolute/path/to/your/config.json"]
    }
  }
}

Windows示例：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "bunx",
      "args": ["@frah/ssh-mcp", "--config", "C:\\Users\\YourName\\ssh-mcp-config.json"]
    }
  }
}

重要提示：

使用时 bunx，您只需指定配置文件路径
中的配置文件路径 --config 必须是绝对的，而不是相对的
bunx将自动下载并运行最新版本的ssh-mcp

2.创建配置文件

确保你有一个 config.json ssh-mcp目录中的文件：

cd /absolute/path/to/ssh-mcp
cp config.example.json config.json
# Edit config.json with your server details

3.验证配置

您可以通过运行以下命令来验证MCP服务器是否已正确配置：

# Test the server directly
bun run /absolute/path/to/ssh-mcp/src/index.ts

# Or inside Claude Code, use the slash command
/mcp

如果服务器成功启动，您应该看到指示服务器正在运行的日志消息。

4.重新启动克劳德代码

配置MCP服务器后，重新启动Claude Code以加载新配置。

5.克劳德代码中的用法

配置后，您可以在Claude Code对话中使用SSH工具：

命令示例：

“显示可用SSH服务器的列表”
“执行 ls -la 在我的开发服务器上”
“上传本地文件 app.log 向 /var/log/app.log 关于生产”
“下载 /etc/nginx/nginx.conf 从web服务器到我的本地计算机”

随着 ssh_list_servers Claude可以自动发现可用的连接，并根据您的自然语言描述选择合适的服务器。

替代方案：使用Node.js

如果你更喜欢使用Node.js而不是Bun，你需要首先构建项目：

bun run build

然后将其配置为：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/ssh-mcp/dist/index.js", "--config", "/absolute/path/to/your/config.json"]
    }
  }
}

笔记：

替换 /absolute/path/to/ssh-mcp 随着 完全绝对路径 到您的ssh-mcp目录
确保Node.js 18+已安装并运行 bun install 安装依赖项
这 --config 如果您的config.json位于ssh-mcp目录中，则参数是可选的

环境变量

LOG_LEVEL：设置日志记录级别（调试、信息、警告、错误）
LOG_FILE：日志文件的路径（可选）

例子：

LOG_LEVEL=debug LOG_FILE=ssh-mcp.log bun run dev

发展

项目结构

ssh-mcp/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── ssh/
│   │   └── connection.ts  # SSH connection management
│   ├── tools/
│   │   ├── execute.ts     # Command execution
│   │   └── file.ts        # File operations
│   ├── security/
│   │   └── validator.ts   # Security validation
│   ├── config/
│   │   └── manager.ts     # Configuration management
│   └── utils/
│       └── logger.ts      # Logging utilities
├── tests/                 # Test files
├── config.example.json    # Example configuration
└── package.json

运行测试

bun test

类型检查

bun run lint

故障排除

MCP配置问题

“未配置MCP服务器”:
- 检查配置中的文件路径是绝对的，而不是相对的
- 验证 .claude.json 文件位置和JSON语法
- 确保Bun已安装并位于PATH中
服务器未启动:
- 手动测试命令： bun run /full/path/to/ssh-mcp/src/index.ts
- 检查TypeScript编译错误
- 验证是否安装了所有依赖项： bun install

连接问题

认证失败：检查用户名/密码或密钥文件权限
连接超时：验证网络连接和防火墙规则
密钥权限错误：确保私钥具有600个权限

命令执行问题

命令被阻止：检查白名单/黑名单配置
超时错误：增加配置或命令中的超时值
权限不足：验证用户在远程服务器上是否具有必要的权限

调试模式

启用调试日志以进行故障排除：

LOG_LEVEL=debug bun run dev

许可证

麻省理工学院

使用说明

SSH MCP服务器

特性

安装

先决条件

快速入门（使用bunx）

本地设置

配置

连接配置选项

全局设置选项

多跳SSH配置

用法

运行服务器

使用bunx（无需安装）

来源

生产建设

命令行选项

可用的MCP工具

1.ssh_execute

2.ssh_upload

3.ssh_download

4.ssh_list_servers

安全功能

命令筛选

内置危险指挥保护

路径消毒

Claude代码集成

1.配置克劳德代码

2.创建配置文件

3.验证配置

4.重新启动克劳德代码

5.克劳德代码中的用法

替代方案：使用Node.js

环境变量

发展

项目结构

运行测试

类型检查

故障排除

MCP配置问题

连接问题

命令执行问题

调试模式

许可证

相关 MCP

远程MacOS控制服务器

终端命令执行服务器

视频播放控制服务器

SFTP-SSH MCP服务器

远程Shell管理协议

调试器HTTP接口插件