Mcp Ssh

开发 TypeScript

🚀 MCP SSH代理

MCP SSH代理是一个基于模型上下文协议（MCP）的服务器，用于管理和控制SSH连接。它能够与Claude Desktop等支持MCP的客户端无缝集成，借助人工智能技术提供强大的SSH操作能力。

🚀 快速开始

📦 安装指南

通过npx安装（推荐）

npx @aiondadotcom/mcp-ssh

全局安装

npm install -g @aiondadotcom/mcp-ssh

本地开发

git clone https://github.com/aiondadotcom/mcp-ssh.git
cd mcp-ssh
npm install
npm start

与Claude Desktop集成

要将此MCP服务器与Claude Desktop配合使用，请在MCP设置文件中添加以下配置：

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

{
"mcpServers": {
"mcp-ssh": {
"command": "npx",
"args": ["@aiondadotcom/mcp-ssh"]
}
}
}

添加此配置后，重启Claude Desktop。在与Claude的对话中即可使用SSH工具。

💻 使用示例

基础用法

上图展示了MCP SSH Agent的实际运行情况，展示了它如何与支持MCP的客户端集成，以提供无缝的SSH操作。

与Claude集成

此截图展示了MCP SSH Agent与Claude的集成，展示了AI助手如何通过MCP协议直接管理SSH连接并执行远程命令。

✨ 主要特性

可靠的SSH操作：使用原生的ssh/scp命令，而非JavaScript SSH库，确保操作的可靠性。
自动发现：从SSH配置文件~/.ssh/config和~/.ssh/known_hosts中自动发现主机。
全面的SSH支持：支持SSH代理、密钥和所有认证方法。
文件操作：使用scp命令上传和下载文件。
批量命令执行：可以按顺序执行多个命令。
错误处理：提供全面的错误报告，并支持超时设置。

📚 详细文档

功能介绍

该代理提供以下MCP工具：

listKnownHosts()：列出所有已知的SSH主机，优先显示~/.ssh/config中的条目，然后是~/.ssh/known_hosts中的其他主机。
runRemoteCommand(hostAlias, command)：使用ssh在远程主机上执行命令。
getHostInfo(hostAlias)：返回特定主机的详细配置信息。
checkConnectivity(hostAlias)：测试与主机的SSH连接性。
uploadFile(hostAlias, localPath, remotePath)：使用scp将文件上传到远程主机。
downloadFile(hostAlias, remotePath, localPath)：使用scp从远程主机下载文件。
runCommandBatch(hostAlias, commands)：按顺序执行多个命令。

配置示例

与Claude Desktop集成

Claude Desktop的配置示例如下：

{
"mcpServers": {
"mcp-ssh": {
"command": "npx",
"args": ["@aiondadotcom/mcp-ssh"]
}
}
}

手动服务器配置

如果您希望手动运行服务器或与其他MCP客户端集成，可以使用以下配置：

{
"servers": {
"mcp-ssh": {
"command": "npx",
"args": ["@aiondadotcom/mcp-ssh"]
}
}
}

使用说明

与Claude Desktop配合使用

配置完成后，您可以向Claude提出以下SSH操作请求：

"列出所有SSH主机"
"检查与生产服务器的连接性"
"在Web服务器上运行命令"
"将文件上传到远程服务器"
"从应用服务器下载日志"

Claude将使用MCP SSH工具安全高效地执行这些操作。

一般使用方法

该代理作为一个通过标准输入输出（STDIO）通信的MCP服务器运行。通过npm安装后，您可以直接使用它：

# 通过npx运行（推荐）
npx @aiondadotcom/mcp-ssh

# 或者全局安装后使用
mcp-ssh

# 开发时使用调试输出运行
npm start

服务器通过标准输入输出以简洁的JSON格式进行通信，非常适合Claude Desktop等MCP客户端。

高级配置

环境变量

MCP_SILENT=true：禁用调试输出（作为MCP服务器使用时会自动设置）

SSH配置

该代理从标准的SSH配置文件中读取信息：

~/.ssh/config：SSH客户端配置
~/.ssh/known_hosts：已知主机密钥

请确保您的SSH密钥已正确配置，并可通过SSH代理或密钥文件访问。

示例`~/.ssh/config`

以下是一个示例SSH配置文件，展示了各种连接场景：

# 全局设置 - 保持连接活跃
ServerAliveInterval 55

# 带有跳板主机的生产服务器
Host prod
Hostname 203.0.113.10
Port 22022
User deploy
IdentityFile ~/.ssh/id_prod_rsa

# 以root用户访问生产服务器（单独条目）
Host root@prod
Hostname 203.0.113.10
Port 22022
User root
IdentityFile ~/.ssh/id_prod_rsa

# 通过生产跳板主机访问的存档服务器
Host archive
Hostname 2001:db8:1f0:cafe::1
Port 22077
User archive-user
ProxyJump prod

# 具有特定配置的Web服务器
Host web1.example.com
Hostname 198.51.100.15
Port 22022
User root
IdentityFile ~/.ssh/id_ed25519

Host web2.example.com
Hostname 198.51.100.25
Port 22022
User root
IdentityFile ~/.ssh/id_ed25519

# 带有自定义密钥的数据库服务器
Host database
Hostname 203.0.113.50
Port 22077
User dbadmin
IdentityFile ~/.ssh/id_database_rsa
IdentitiesOnly yes

# 邮件服务器
Host mail1
Hostname 198.51.100.88
Port 22078
User mailuser

Host root@mail1
Hostname 198.51.100.88
Port 22078
User root

# 监控服务器
Host monitor
Hostname 203.0.113.100
Port 22077
User monitoring
IdentityFile ~/.ssh/id_monitor_ed25519
IdentitiesOnly yes

# 负载均衡器
Host lb-a
Hostname 198.51.100.200
Port 22077
User root

Host lb-b
Hostname 198.51.100.201
Port 22077
User root

此配置展示了：

全局设置：使用ServerAliveInterval保持连接活跃。
自定义端口：使用非标准SSH端口提高安全性。
多用户配置：同一主机的不同用户账户（如prod和root@prod）。
跳板主机：使用ProxyJump通过堡垒主机访问服务器。
IPv6地址：支持现代网络。
身份文件：为不同服务器使用特定的SSH密钥。
安全选项：使用IdentitiesOnly yes仅使用指定的密钥。

MCP SSH代理如何使用您的配置

MCP SSH代理会自动发现并使用您的SSH配置：

主机发现：~/.ssh/config中的所有主机都可自动使用。
原生SSH：使用系统的ssh命令，因此所有配置选项都有效。
认证：遵循您的SSH代理、密钥文件和认证设置。
跳板主机：支持复杂的代理链和堡垒主机设置。
端口转发：可与自定义端口和连接选项配合使用。

与Claude Desktop的示例用法：

"列出我的SSH主机" → 显示所有配置的主机，包括prod、archive、web1.example.com等。
"连接到存档服务器" → 自动使用ProxyJump配置。
"在web1.example.com上运行df -h" → 使用正确的用户、端口和密钥进行连接。
"将文件上传到数据库服务器" → 使用特定的身份文件和端口配置。

故障排除

常见问题

命令未找到：确保ssh和scp已安装并在您的系统路径中。
权限被拒绝：检查SSH密钥权限和SSH代理。
主机未找到：验证主机是否存在于~/.ssh/config或~/.ssh/known_hosts中。
连接超时：检查网络连接性和防火墙设置。

调试模式

运行时启用调试输出以查看详细的操作日志：

# 启用调试模式
MCP_SILENT=false npx @aiondadotcom/mcp-ssh

SSH密钥设置指南

为了使MCP SSH代理正常工作，您需要设置SSH密钥认证。以下是完整的指南：

1. 创建SSH密钥

生成新的SSH密钥对（建议使用Ed25519以提高安全性）：

# 生成Ed25519密钥（推荐）
ssh-keygen -t ed25519 -C "your-email@example.com"

# 或者生成RSA密钥（如果不支持Ed25519）
ssh-keygen -t rsa -b 4096 -C "your-email@example.com"

重要提示：提示输入密码短语时，请留空（按Enter键）。MCP SSH代理以非交互式方式运行，无法处理受密码保护的密钥。

Enter passphrase (empty for no passphrase): [Press Enter]
Enter same passphrase again: [Press Enter]

这将创建两个文件：

~/.ssh/id_ed25519（私钥） - 请妥善保管！
~/.ssh/id_ed25519.pub（公钥） - 将其复制到服务器。

2. 在远程服务器上安装公钥

将您的公钥复制到远程服务器的authorized_keys文件中：

# 方法1：使用ssh-copy-id（最简单）
ssh-copy-id user@hostname

# 方法2：手动复制
cat ~/.ssh/id_ed25519.pub | ssh user@hostname "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

# 方法3：手动复制粘贴
cat ~/.ssh/id_ed25519.pub
# 然后SSH到服务器并粘贴到~/.ssh/authorized_keys

3. 服务器端SSH配置

要在SSH服务器上启用安全的仅密钥认证，请编辑/etc/ssh/sshd_config：

# 编辑SSH守护进程配置
sudo nano /etc/ssh/sshd_config

添加或修改以下设置：

# 启用公钥认证
PubkeyAuthentication yes
AuthorizedKeysFile .ssh/authorized_keys

# 禁用密码认证（安全最佳实践）
PasswordAuthentication no
ChallengeResponseAuthentication no
UsePAM no

# 根用户登录选项（选择一个）：
# 选项1：仅允许使用SSH密钥进行根用户登录（推荐用于管理任务）
PermitRootLogin prohibit-password

# 选项2：完全禁用根用户登录（最安全，但需要sudo访问权限）
# PermitRootLogin no

# 可选：将SSH访问限制为特定用户
AllowUsers deploy root admin

# 可选：更改默认端口以提高安全性
Port 22022

编辑完成后，重启SSH服务：

# 在Ubuntu/Debian上
sudo systemctl restart ssh

# 在CentOS/RHEL/Fedora上
sudo systemctl restart sshd

# 在macOS上
sudo launchctl unload /System/Library/LaunchDaemons/ssh.plist
sudo launchctl load /System/Library/LaunchDaemons/ssh.plist

4. 设置正确的权限

SSH对文件权限要求非常严格。请正确设置权限： 在本地机器上：

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
chmod 644 ~/.ssh/config
chmod 644 ~/.ssh/known_hosts

在远程服务器上：

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

5. 测试SSH密钥认证

在使用MCP SSH代理之前，请测试您的连接：

# 测试连接
ssh -i ~/.ssh/id_ed25519 user@hostname

# 使用详细输出进行调试
ssh -v -i ~/.ssh/id_ed25519 user@hostname

# 测试特定配置
ssh -F ~/.ssh/config hostname

6. 为不同服务器使用多个密钥

您可以为不同的服务器创建不同的密钥：

# 创建特定的密钥
ssh-keygen -t ed25519 -f ~/.ssh/id_production -C "production-server"
ssh-keygen -t ed25519 -f ~/.ssh/id_staging -C "staging-server"

然后在~/.ssh/config中进行配置：

Host production
Hostname prod.example.com
User deploy
IdentityFile ~/.ssh/id_production
IdentitiesOnly yes

Host staging
Hostname staging.example.com
User deploy
IdentityFile ~/.ssh/id_staging
IdentitiesOnly yes

安全最佳实践

SSH密钥安全

切勿使用受密码保护的密钥与MCP SSH代理配合使用。
切勿共享私钥 - 私钥应仅保留在您的机器上。
尽可能使用Ed25519密钥（比RSA更安全）。
为不同环境/目的创建单独的密钥。
定期轮换密钥（每6 - 12个月）。

服务器安全

完全禁用密码认证。
使用非标准SSH端口以减少自动化攻击。
使用AllowUsers将SSH访问限制为特定用户。
选择合适的根用户登录策略：
- PermitRootLogin prohibit-password - 仅允许使用SSH密钥进行根用户访问（推荐用于管理任务）。
- PermitRootLogin no - 完全禁用根用户登录（最安全，但需要sudo访问权限）。
为所有账户启用仅SSH密钥认证。
考虑使用跳板主机以增加安全层。

网络安全

为生产服务器使用VPN或堡垒主机。
实施fail2ban以阻止暴力破解尝试。
定期监控SSH日志。
谨慎使用SSH密钥转发（不需要时禁用）。

🔧 技术细节

项目结构

mcp-ssh/
├── server-simple.mjs          # 主要的MCP服务器实现
├── package.json               # 依赖项和脚本
├── README.md                  # 文档
├── LICENSE                    # MIT许可证
├── CHANGELOG.md               # 发布历史
├── PUBLISHING.md              # 发布说明
├── start.sh                   # 开发启动脚本
├── start-silent.sh            # 静默启动脚本
├── doc/
│   ├── example.png            # 使用示例截图
│   └── Claude.png             # Claude Desktop集成示例
├── src/                       # TypeScript源文件（开发用）
│   ├── ssh-client.ts          # SSH操作实现
│   ├── ssh-config-parser.ts   # SSH配置解析
│   └── types.ts               # 类型定义
└── tsconfig.json              # TypeScript配置

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

关于

本项目由 aionda.com 维护，通过模型上下文协议（MCP）为AI助手和SSH基础设施之间提供了可靠的桥梁。

贡献

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

0 条评论
分类：开发

Mcp Ssh

🚀 MCP SSH代理

🚀 快速开始

📦 安装指南

通过npx安装（推荐）

全局安装

本地开发

与Claude Desktop集成

💻 使用示例

基础用法

与Claude集成

✨ 主要特性

📚 详细文档

功能介绍

配置示例

与Claude Desktop集成

手动服务器配置

使用说明

与Claude Desktop配合使用

一般使用方法

高级配置

环境变量

SSH配置

示例~/.ssh/config

MCP SSH代理如何使用您的配置

故障排除

常见问题

调试模式

SSH密钥设置指南

1. 创建SSH密钥

2. 在远程服务器上安装公钥

3. 服务器端SSH配置

4. 设置正确的权限

5. 测试SSH密钥认证

6. 为不同服务器使用多个密钥

安全最佳实践

SSH密钥安全

服务器安全

网络安全

🔧 技术细节

项目结构

📄 许可证

关于

贡献

0 个评论

相似服务问题

相关AI产品

热议话题 »

示例`~/.ssh/config`