MCP SSH代理

![Tests](https://github.com/AiondaDotCom/mcp-ssh/actions/workflows/test.yml)

用于管理和控制SSH连接的模型上下文协议（MCP）服务器。该服务器与Claude Desktop和其他MCP兼容客户端无缝集成，提供AI驱动的SSH操作。

概述

此MCP服务器通过一个干净、标准化的接口提供SSH操作，该接口可供MCP兼容的语言模型（如Claude Desktop）使用。服务器会自动从您的 ~/.ssh/config 和 ~/.ssh/known_hosts 使用本地SSH工具进行文件和执行命令，以获得最大的可靠性。

快速开始

桌面扩展安装（推荐）

安装MCP SSH代理的最简单方法是通过桌面扩展（.dxt）格式：

下载最新版 mcp-ssh-*.dxt 文件来自
双击 .dxt 将其安装在Claude Desktop中的文件
SSH工具将在您与Claude的对话中自动可用

替代安装方法

通过npx安装

npx @aiondadotcom/mcp-ssh

手动克劳德桌面配置

要使用手动配置将此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。SSH工具将可用于您与Claude的对话。

全球安装

npm install -g @aiondadotcom/mcp-ssh

本地开发

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

示例用法

MCP SSH Agent Example

上面的屏幕截图显示了MCP SSH代理的运行情况，演示了它如何与MCP兼容的客户端集成，以提供无缝的SSH操作。

与Claude整合

Claude MCP Integration

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

主要特点

可靠的SSH：使用本地 ssh/scp 命令而不是JavaScript SSH库
自动发现：从SSH配置和known_hosts文件中查找主机
完全SSH支持：适用于SSH代理、密钥和所有身份验证方法
密码认证：支持基于密码的SSH登录和密钥密码 @password 注释——密码永远不会离开你的机器
文件操作：使用上传和下载文件 scp
批处理命令：按顺序执行多个命令
错误处理：具有超时功能的全面错误报告

函数

该代理提供以下MCP工具：

listKnownHosts（） -列出所有已知的SSH主机，优先考虑~/.SSH/config中的条目，然后是~/.SSH/known_hosts中的其他主机
runRemoteCommand（hostAlias，命令） -使用以下命令在远程主机上执行命令 ssh
getHostInfo（主机别名） -返回特定主机的详细配置
checkConnectivity（主机别名） -测试与主机的SSH连接
uploadFile（主机别名、本地路径、远程路径） -使用以下命令将文件上传到远程主机 scp
下载文件（hostAlias、remotePath、localPath） -使用从远程主机下载文件 scp
runCommandBatch（hostAlias，命令） -按顺序执行多个命令

配置示例

Claude桌面集成

以下是Claude Desktop配置的外观：

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

手动服务器配置

如果您更喜欢手动运行服务器或将其与其他MCP客户端集成：

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

需求

Node.js 20或更高版本
已安装SSH客户端(ssh 和 scp 可用命令）
SSH配置文件(~/.ssh/config 和 ~/.ssh/known_hosts)

使用Claude Desktop

配置后，您可以要求Claude帮助您进行SSH操作，例如：

“列出我的所有SSH主机”
“检查与生产服务器的连接”
“在我的web服务器上运行命令”
“将此文件上载到我的远程服务器”
“从我的应用程序服务器下载日志”

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

用法

该代理作为STDIO上的模型上下文协议服务器运行。当通过npm安装时，你可以直接使用它：

# Run via npx (recommended)
npx @aiondadotcom/mcp-ssh

# Or if installed globally
mcp-ssh

# For development - run with debug output
npm start

服务器通过STDIO通过干净的JSON进行通信，使其非常适合像Claude Desktop这样的MCP客户端。

高级配置

环境变量

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

SSH配置

代理从标准SSH配置文件中读取：

~/.ssh/config -SSH客户端配置（支持Include指令）
~/.ssh/known_hosts -已知主机密钥

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

密码认证

对于需要基于密码的身份验证的主机（常见于交换机和路由器等网络基础设施），您可以直接将密码存储在 ~/.ssh/config 使用特殊注释：

Host myrouter
    HostName 192.168.1.1
    User admin
    # @password:yourSecretPassword

Host myserver
    HostName 10.0.0.5
    User deploy
    IdentityFile ~/.ssh/id_rsa
    # @password:myKeyPassphrase

它是如何工作的：

这 # @password: 注释已读取本地通过MCP服务器--密码从不到达AI模型或任何云提供商
适用于登录密码和SSH密钥密码
密码首先被拆分 :，因此密码包含 : 支持
列出主机时，仅 passwordAuth: true 显示-实际密码永远不会暴露

安全要求：

SSH配置文件必须有 600 使用时的权限 @password 注释
如果文件权限太开放，MCP服务器将拒绝启动
使用以下方式修复： chmod 600 ~/.ssh/config

包括指令支持

MCP SSH代理完全支持SSH Include 跨多个文件组织配置的指令。但是，有一个重要的SSH错误需要注意：

⚠️ SSH包含指令错误警告

SSH有一个配置解析错误，其中 Include 陈述 必须放在开头 你的 ~/.ssh/config 文件正常工作。如果放在末尾，SSH将读取它们，但不会正确应用包含的配置。

✅ 正确的位置（在开头）：

# ~/.ssh/config
Include ~/.ssh/config.d/*
Include ~/.ssh/work-hosts

# Global settings
ServerAliveInterval 55

# Host definitions
Host myserver
    HostName example.com

❌ 位置不正确（在末尾）-不起作用：

# ~/.ssh/config
# Global settings
ServerAliveInterval 55

# Host definitions
Host myserver
    HostName example.com

# These Include statements won't work properly due to SSH bug:
Include ~/.ssh/config.d/*
Include ~/.ssh/work-hosts

MCP SSH代理正确处理 Include 指令，无论它们在文件中的位置如何，因此即使SSH本身在配置上有问题，您也会得到完整的主机发现。

示例~/.ssh/config

这是一个示例SSH配置文件，演示了各种连接场景，包括Include指令和 @password 基于密码的身份验证注释：

# Include directives must be at the beginning due to SSH bug
Include ~/.ssh/config.d/*
Include ~/.ssh/work-servers

# Global settings - keep connections alive
ServerAliveInterval 55

# Production server with jump host
Host prod
    Hostname 203.0.113.10
    Port 22022
    User deploy
    IdentityFile ~/.ssh/id_prod_rsa

# Root access to production (separate entry)
Host root@prod
    Hostname 203.0.113.10
    Port 22022
    User root
    IdentityFile ~/.ssh/id_prod_rsa

# Router with password authentication (no SSH key)
Host router
    Hostname 192.168.1.1
    User admin
    # @password:cQbG0q@019TAoehZel7V

# Archive server accessed through production jump host
Host archive
    Hostname 2001:db8:1f0:cafe::1
    Port 22077
    User archive-user
    ProxyJump prod

# Web servers with specific configurations
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

# Database server with custom key and passphrase-protected key
Host database
    Hostname 203.0.113.50
    Port 22077
    User dbadmin
    IdentityFile ~/.ssh/id_database_rsa
    IdentitiesOnly yes
    # @password:U1Jqn=NoKdELYn&h1jVT

# Mail servers (password auth, no SSH key)
Host mail1
    Hostname 198.51.100.88
    Port 22078
    User mailuser
    # @password:7iBiV8lyoq*zANv46ALD

Host root@mail1
    Hostname 198.51.100.88
    Port 22078
    User root
    # @password:MRDHI2h!zhhN=ZJIxWzH

# Monitoring server
Host monitor
    Hostname 203.0.113.100
    Port 22077
    User monitoring
    IdentityFile ~/.ssh/id_monitor_ed25519
    IdentitiesOnly yes

# Load balancers
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 仅使用指定的密钥
密码认证: # @password: 不支持SSH密钥的设备（如路由器、交换机）或密码保护密钥的注释

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 已安装并位于您的PATH中
权限不足：检查SSH密钥权限和SSH代理
找不到主机：验证主机是否存在于 ~/.ssh/config 或 ~/.ssh/known_hosts
连接超时：检查网络连接和防火墙设置

调试模式

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

# Enable debug mode
MCP_SILENT=false npx @aiondadotcom/mcp-ssh

SSH密钥设置指南

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

1.创建SSH密钥

生成新的SSH密钥对（使用Ed25519以获得更好的安全性）：

# Generate Ed25519 key (recommended)
ssh-keygen -t ed25519 -C "your-email@example.com"

# Or generate RSA key (if Ed25519 is not supported)
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文件中：

# Method 1: Using ssh-copy-id (easiest)
ssh-copy-id user@hostname

# Method 2: Manual copy
cat ~/.ssh/id_ed25519.pub | ssh user@hostname "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

# Method 3: Copy and paste manually
cat ~/.ssh/id_ed25519.pub
# Then SSH to the server and paste into ~/.ssh/authorized_keys

3.服务器端SSH配置

要在SSH服务器上启用仅使用安全密钥的身份验证，请编辑 /etc/ssh/sshd_config:

# Edit SSH daemon configuration
sudo nano /etc/ssh/sshd_config

添加或修改这些设置：

# Enable public key authentication
PubkeyAuthentication yes
AuthorizedKeysFile .ssh/authorized_keys

# Disable password authentication (security best practice)
PasswordAuthentication no
ChallengeResponseAuthentication no
UsePAM no

# Root login options (choose one):
# Option 1: Allow root login with SSH keys only (recommended for admin access)
PermitRootLogin prohibit-password

# Option 2: Completely disable root login (most secure, but less flexible)
# PermitRootLogin no

# Optional: Restrict SSH to specific users
AllowUsers deploy root admin

# Optional: Change default port for security
Port 22022

编辑后，重新启动SSH服务：

# On Ubuntu/Debian
sudo systemctl restart ssh

# On CentOS/RHEL/Fedora
sudo systemctl restart sshd

# On 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代理之前测试您的连接：

# Test connection
ssh -i ~/.ssh/id_ed25519 user@hostname

# Test with verbose output for debugging
ssh -v -i ~/.ssh/id_ed25519 user@hostname

# Test specific configuration
ssh -F ~/.ssh/config hostname

6.不同服务器的多个密钥

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

# Create specific keys
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

威胁模型和信任边界

MCP SSH代理使LLM能够驱动 ssh 和 scp 代表你。在使用它之前，了解控制LLM指令的攻击者是什么（例如通过 提示注入 通过网页、电子邮件、存储库文件或其他MCP服务器的输出）可以做到：

runRemoteCommand 在您配置的每台主机上执行完整的远程代码。 如果你的 ~/.ssh/config 包含以下条目 production，LLM可以在该主机上以该用户的身份运行任意命令。这是该工具的目的，而不是一个bug——但这意味着你应该只配置你愿意让LLM接触的主机，并首选特权最低的帐户。
uploadFile 和 downloadFile 授予LLM访问本地文件系统的权限 具有运行MCP服务器的用户的权限。LLM可以读取进程可以读取的任何文件（包括 ~/.ssh/id_*、浏览器数据、源树， .env 文件）并写入它可以写入的任何路径（包括 ~/.ssh/authorized_keys).路径参数没有沙盒，因为该工具的约定是“传输任意文件”。
MCP服务器通过STDIO在本地运行，但LLM不受信任。 STDIO仅描述传输—— *内容* 工具参数由模型选择，模型可以通过在对话中摄入的任何不受信任的文本来控制。
# @password: 注释被排除在LLM的上下文之外，但他们住在 ~/.ssh/config 在磁盘上。任何让攻击者读取任意本地文件的东西（见上文）也会暴露这些密码。注释仅防止LLM通过MCP协议看到密码，而不是防止本地文件泄露。

建议

在下运行MCP SSH代理 专用、无特权的操作系统用户 其主目录仅包含您实际希望LLM能够使用的SSH配置和密钥。
或者在一个 容器/沙箱 以最小 ~/.ssh 并且无法访问您机器上的其他机密。
保持 ~/.ssh/config 将LLM扩展到您信任的最小主机集。尽可能在远程使用受限shell用户。
将LLM摄入不受信任内容（网页、电子邮件、第三方存储库、其他MCP服务器的输出）的任何会话视为对MCP SSH操作的潜在敌意。
通过GitHub在此存储库上的私有漏洞报告报告可疑漏洞。

安全最佳实践

SSH密钥安全

切勿使用受密码保护的密钥 使用MCP SSH代理
从不共享私钥 -它们应该只留在你的机器上
使用Ed25519键 如果可能（比RSA更安全）
创建单独的密钥 适用于不同的环境/目的
定期旋转按键 （每6-12个月一次）

服务器安全

禁用密码身份验证 完全
使用非标准SSH端口 减少自动攻击
限制SSH访问 对于特定用户 AllowUsers
选择适当的root登录策略:

- PermitRootLogin prohibit-password -仅允许使用SSH密钥进行root访问（建议用于管理任务） - PermitRootLogin no -完全禁用root登录（最安全，但需要sudo访问）

启用仅SSH密钥身份验证 对于所有帐户
考虑使用跳转主机 用于附加安全层

网络安全

使用VPN或堡垒主机 用于生产服务器
机具故障2ban 阻止暴力企图
监视SSH日志 定期
谨慎使用SSH密钥转发 （不需要时禁用）

构建桌面扩展

对于希望在本地构建DXT包的开发人员：

先决条件

Node.js 20或更高版本
npm

构建DXT包

# Install dependencies
npm install

# Build the DXT package
npm run build:dxt

这创建了一个 .dxt 文件在 build/ 可以安装在Claude Desktop中的目录。

发布DXT版本

要发布新的DXT版本，请执行以下操作：

# Build the DXT package
npm run build:dxt

# Create a GitHub release with the DXT file
gh release create v1.0.3 build/mcp-ssh-1.0.3.dxt --title "Release v1.0.3" --notes "MCP SSH Agent v1.0.3"

DXT文件将作为发布资产供用户下载和安装。

贡献

欢迎投稿！请随时提交拉取请求。

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

项目结构

mcp-ssh/
├── server.mjs          # Main MCP server implementation
├── manifest.json              # DXT package manifest
├── package.json               # Dependencies and scripts
├── README.md                  # Documentation
├── LICENSE                    # MIT License
├── CHANGELOG.md               # Release history
├── PUBLISHING.md              # Publishing instructions
├── start.sh                   # Development startup script
├── start-silent.sh            # Silent startup script
├── scripts/
│   └── build-dxt.sh           # DXT package build script
├── doc/
│   ├── example.png            # Usage example screenshot
│   └── Claude.png             # Claude Desktop integration example
└── doc/                       # Documentation assets

关于

该项目由以下人员维护 aionda.com 并通过模型上下文协议在AI助手和SSH基础设施之间提供可靠的桥梁。

MCP SSH Agent

快速接入

详细介绍