SSH-MCP服务器

Name: SSH-MCP服务器
Author: idletoaster

作者：idletoaster2 星标更新：2025-06-12

安装使用来源：spider==github.com

项目介绍

🚀 SSH MCP 服务器（Node.js）

一个安全、高性能的模型上下文协议（MCP）服务器，使像 Claude Desktop 这样的 AI 助手能够在远程服务器上执行 SSH 命令。使用 Node.js 和官方 MCP SDK 构建，以实现最大兼容性和可靠性。

🔄 版本 2.1.0 - 高效令牌文件操作：完全重写为 Node.js 并使用官方 MCP SDK —— 消除了所有之前的 Go 兼容性问题！

✨ 特点

🔐 安全 SSH：支持多种密钥格式的私钥认证
🤖 AI 就绪：与 Claude Desktop 和其他 AI 工具集成的官方 MCP SDK
⚡ 高性能：Node.js 异步架构实现快速命令执行
📦 零配置：通过 NPX 单命令安装 —— 不需要编译
🌐 通用性：纯 JavaScript 可在 Windows、macOS 和 Linux 上运行
🛡️ 类型安全：使用现代 JavaScript 和全面的错误处理构建
📋 标准合规：使用官方 @modelcontextprotocol/sdk

🚀 快速开始

安装及使用

# 使用 NPX 直接安装（推荐）
npx @idletoaster/ssh-mcp-server@latest

# 或全局安装
npm install -g @idletoaster/ssh-mcp-server

Claude Desktop 配置

添加到您的 Claude Desktop MCP 配置文件中：

{
  "mcpServers": {
    "ssh": {
      "command": "npx",
      "args": ["-y", "@idletoaster/ssh-mcp-server@latest"],
      "env": {}
    }
  }
}

就这样！ 现在 Claude 可以在您的远程服务器上执行 SSH 命令了。

💬 使用示例

配置完成后，Claude 可以帮助您执行如下命令：

“检查生产服务器 192.168.1.100 的磁盘使用情况”

“作为用户 admin 在 server.example.com 上重启 nginx 服务”

“使用我的 SSH 密钥显示我的 Ubuntu 服务器上的运行进程”

手动工具使用

{
  "tool": "remote-ssh",
  "arguments": {
    "host": "192.168.1.100",
    "user": "ubuntu",
    "command": "df -h",
    "privateKeyPath": "/home/user/.ssh/id_rsa"
  }
}

🔧 配置

SSH 密钥认证

该服务器支持多种认证方法：

1. 显式密钥路径

{
  "privateKeyPath": "/path/to/your/private/key"
}

2. 环境变量

export SSH_PRIVATE_KEY="/home/user/.ssh/id_rsa"

3. 自动发现

自动搜索以下位置的密钥：

~/.ssh/id_rsa
~/.ssh/id_ed25519
~/.ssh/id_ecdsa

支持的密钥格式

✅ RSA 密钥（id_rsa）
✅ ED25519 密钥（id_ed25519）
✅ ECDSA 密钥（id_ecdsa）
✅ OpenSSH 格式
✅ PEM 格式

🛠️ 开发

先决条件

Node.js 18+（检查：node --version）
NPM 9+（检查：npm --version）

安装 Node.js

Windows：

从 nodejs.org 下载或使用 Chocolatey：

choco install nodejs

Linux（Ubuntu/Debian）：

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Linux（CentOS/RHEL）：

curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

macOS：

brew install node

从源代码构建

# 克隆仓库
git clone https://github.com/idletoaster/ssh-mcp-server.git
cd ssh-mcp-server

# 安装依赖
npm install

# 本地运行
npm start

# 开发模式自动重载
npm run dev

🏗️ 架构

ssh-mcp-server/
├── package.json          # NPM 配置及依赖
├── index.js              # 主 MCP 服务器（官方 SDK）
├── lib/
│   └── ssh-client.js     # SSH 连接管理
├── README.md             # 文档
├── LICENSE               # MIT 许可证
└── .gitignore            # Node.js .gitignore

技术栈

运行时：Node.js 18+ with ES Modules
MCP SDK：@modelcontextprotocol/sdk（官方）
SSH：Node.js 的 ssh2 库
分发：NPM，直接 NPX 执行

🔒 安全

最佳实践

✅ 私钥认证（无密码）
✅ 可配置的 SSH 算法和超时
✅ 无持久连接（基于会话）
✅ 输入验证和清理
✅ 全面的错误处理

安全指南

🔐 私钥存储权限严格（chmod 600）
🌐 当可能时使用 SSH 密钥短语
🛡️ 在 ~/.ssh/config 中限制 SSH 密钥到特定主机
📝 监控 SSH 访问日志
🚫 除非绝对必要，否则不要以 root 身份运行

网络安全

# 示例 SSH 配置以限制访问
Host production-server
    HostName 192.168.1.100
    User deploy
    IdentityFile ~/.ssh/production_key
    IdentitiesOnly yes
    StrictHostKeyChecking yes

🧪 测试

本地测试

# 测试 MCP 服务器
echo '{"host":"test.server.com","user":"testuser","command":"whoami"}' | npm start

集成测试

# 验证 Node.js 安装
node --version  # 应为 18+
npm --version   # 应为 9+

# 测试 NPX 执行
npx @idletoaster/ssh-mcp-server@latest --help

🌍 兼容性

操作系统

✅ Windows 10/11（x64, ARM64）
✅ macOS 12+（Intel & Apple Silicon）
✅ Linux（x64, ARM64）- 所有主要发行版

AI 平台

🤖 Claude Desktop（主要目标）
🤖 Cursor IDE
🤖 任何 MCP 兼容的应用程序

Node.js 兼容性

✅ Node.js 18.x（长期支持）
✅ Node.js 20.x（长期支持）
✅ Node.js 22.x（当前）

📊 从 v1.x（Go）迁移

从 Go 版本升级？ Node.js 版本提供了：

✅ 改进

无需编译 - 不再需要二进制构建
更好的兼容性 - 官方 MCP SDK
更快的开发 - 直接代码更改
更简单的部署 - 纯 NPX 分发
无协议问题 - 官方 Anthropic SDK

🔄 迁移步骤

卸载旧版本：删除基于 Go 的安装
安装新版本：npx @idletoaster/ssh-mcp-server@latest
更新 Claude 配置：相同的配置即可工作！
测试连接：验证 SSH 功能

🤝 贡献

开发流程

分叉仓库
创建功能分支：git checkout -b feature/amazing-feature
进行更改
彻底测试：npm test
提交拉取请求

代码风格

使用 ES6+ 现代 JavaScript
遵循 Node.js 最佳实践
为函数添加 JSDoc 注释
使用现有模式进行验证

📄 许可证

MIT 许可证 - 详情见 LICENSE 文件。

🙏 致谢

@modelcontextprotocol/sdk - 官方 MCP SDK
ssh2 - Node.js SSH 客户端
Claude Desktop - 主要目标平台
Model Context Protocol - 标准规范

📞 支持

📋 问题：GitHub Issues
💬 讨论：GitHub Discussions

为 AI 开发社区使用 Node.js 和官方 MCP SDK 构建

🆕 新增功能 v2.1.0：高效令牌文件操作

增强功能，包含 4 个强大的工具，灵感来自 Desktop Commander，优化了令牌使用：

🎯 高效令牌工具

ssh-edit-block - 编辑特定文本块（相比全文重写节省 80-90% 令牌）
ssh-read-lines - 按行号读取文件部分（对大文件节省大量令牌）
ssh-search-code - 模式搜索，无需读取整个文件
ssh-write-chunk - 高效内容写入，支持追加/重写模式

💡 优势

文件操作减少 80-90% 令牌
小改动无需全文重写
大型代码库的部分文件读取
无令牌开销的模式搜索

📖 新工具用法

// 编辑特定文本块
{
  "name": "ssh-edit-block",
  "arguments": {
    "host": "server.com",
    "user": "username",
    "filePath": "/path/to/file.js",
    "oldText": "version: '2.0.0'",
    "newText": "version: '2.1.0'"
  }
}

// 仅读取特定行
{
  "name": "ssh-read-lines",
  "arguments": {
    "host": "server.com",
    "user": "username",
    "filePath": "/path/to/large-file.js",
    "startLine": 100,
    "endLine": 150
  }
}

// 高效模式搜索
{
  "name": "ssh-search-code",
  "arguments": {
    "host": "server.com",
    "user": "username",
    "path": "/project",
    "pattern": "function.*export",
    "filePattern": "*.js"
  }
}