MCP SSH Server
一个用于大模型 SSH 远程连接多轮交互的 MCP (Model Context Protocol) 服务。
](https://python.org)  
功能特性
- 🔐 安全的 SSH 连接管理: 支持密码和密钥认证，连接池和自动重连
- 💬 多轮交互会话: 维护会话状态、历史记录和上下文信息
- ⚡ 命令执行: 在远程服务器上安全执行命令，支持超时控制
- 📁 文件操作: 上传、下载和浏览远程文件
- 🐚 交互式 Shell: 支持持久化 shell 会话和实时交互
- 🔧 灵活配置: 支持环境变量和配置文件
- 📊 完整日志: 详细的操作日志和错误追踪
快速开始
安装
# 克隆项目
git clone https://github.com/fairyto2/remote-shell-mcp-server.git
cd remote-shell-mcp-server
# 安装依赖
uv install
# 安装项目
uv pip install -e .运行模式
本项目支持两种运行模式：
1. 本地 MCP 服务器（标准模式）
uv run mcp_ssh_server适用于与本地 AI 助手（如 Claude Desktop）集成。
2. 远程 MCP 服务器
uv run python -m mcp_ssh_server.remote_server适用于通过网络提供 MCP 服务，支持多客户端连接。默认端口为 8080。
远程连接配置：
在客户端（如 Claude Desktop）的配置文件中添加：
{
"mcpServers": {
"remote-ssh": {
"url": "http://:8080/mcp"
}
}
}注意：服务器已配置为允许所有 Host 和 Origin，因此可以安全地部署在远程服务器上并通过 IP 地址访问，不会出现 421 Misdirected Request 错误。
详细配置请参考 远程服务器文档。
基本使用
- 启动服务器
uv run mcp_ssh_server- 建立 SSH 连接
{
"name": "ssh_connect",
"arguments": {
"name": "my-server",
"host": "example.com",
"username": "user",
"password": "password"
}
}- 创建会话
{
"name": "session_create",
"arguments": {
"name": "my-session",
"connection": "my-server"
}
}- 执行命令
{
"name": "session_execute",
"arguments": {
"session_id": "会话ID",
"command": "ls -la"
}
}MCP 工具列表
SSH 连接管理
ssh_connect- 建立 SSH 连接ssh_disconnect- 断开 SSH 连接ssh_list_connections- 列出所有 SSH 连接ssh_execute- 在远程服务器上执行命令
文件操作
ssh_upload- 上传文件到远程服务器ssh_download- 从远程服务器下载文件ssh_list- 列出远程目录内容
交互式 Shell
ssh_shell- 创建交互式 shellshell_send- 在 shell 中发送命令shell_close- 关闭交互式 shell
会话管理
session_create- 创建新的交互会话session_list- 列出所有会话session_delete- 删除会话session_execute- 在会话中执行命令session_history- 获取会话历史记录session_context- 获取会话上下文信息
配置
环境变量
| 变量名 | 描述 | 默认值 |
|---|---|---|
MCP_SSH_LOG_LEVEL | 日志级别 | INFO |
MCP_SSH_TIMEOUT | 默认 SSH 连接超时时间（秒） | 30 |
MCP_SSH_CONFIG | 配置文件路径 | ~/.mcp_ssh_config.json |
配置文件
示例配置文件 (config/example.json):
{
"log_level": "INFO",
"default_timeout": 30,
"max_sessions": 100,
"connections": {
"prod-server": {
"host": "prod.example.com",
"username": "deploy",
"key_filename": "/path/to/private/key",
"port": 22,
"timeout": 30
}
}
}架构设计
核心组件
- SSHConnectionManager: SSH 连接管理器
- 连接池管理 - 连接状态监控 - 自动重连机制 - 文件操作支持
- SessionManager: 会话管理器
- 多会话支持 - 历史记录管理 - 上下文信息维护 - 会话导入/导出
- MCPSshServer: MCP 服务器
- 协议处理 - 工具注册 - 请求路由
安全特性
- 🔒 连接隔离: 每个会话使用独立的 SSH 连接
- 🔑 认证支持: 支持密码和密钥认证
- ⏱️ 超时保护: 命令执行超时机制
- 📝 日志审计: 完整的操作日志记录
- 🧹 自动清理: 定期清理不活跃会话
开发
项目结构
mcp_ssh_server/
├── __init__.py # 包初始化
├── server.py # MCP 服务器主类
├── ssh_manager.py # SSH 连接管理
├── session_manager.py # 会话管理
└── config.py # 配置管理
tests/ # 测试文件
├── conftest.py # 测试配置
├── test_simple_core.py # 核心逻辑测试
└── ...
docs/ # 文档
├── quickstart.md # 快速开始指南
├── usage.md # 完整使用文档
└── ...
config/ # 配置文件
└── example.json # 配置示例运行测试
# 运行所有测试
uv run pytest
# 运行特定测试
uv run pytest tests/test_simple_core.py -v
# 生成覆盖率报告
uv run pytest --cov=mcp_ssh_server代码质量
# 代码格式化
uv run black mcp_ssh_server/
uv run isort mcp_ssh_server/
# 类型检查
uv run mypy mcp_ssh_server/
# 代码检查
uv run ruff check mcp_ssh_server/故障排除
常见问题
- SSH 连接失败
- 检查网络连接和防火墙设置 - 验证认证信息（密码/密钥） - 确认 SSH 服务运行状态
- 命令执行超时
- 增加超时时间设置 - 检查命令执行时间 - 验证服务器响应速度
- 文件传输失败
- 检查文件路径和权限 - 确认磁盘空间充足 - 验证网络稳定性
调试模式
启用详细日志：
MCP_SSH_LOG_LEVEL=DEBUG uv run mcp_ssh_server路线图
- [ ] 支持 SSH 代理转发
- [ ] 添加 SFTP 文件编辑功能
- [ ] 实现命令模板和快捷方式
- [ ] 支持多服务器批量操作
- [ ] 添加 Web 管理界面
- [ ] 集成监控和告警
贡献
我们欢迎各种形式的贡献！
- Fork 项目
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
许可证
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
致谢
- Model Context Protocol (MCP)
- Paramiko - SSH 库
- FastAPI - API 框架灵感
联系方式
- 项目主页: https://github.com/fairyto2/remote-shell-mcp-server
- 问题反馈: https://github.com/fairyto2/remote-shell-mcp-server/issues
- 文档: https://github.com/fairyto2/remote-shell-mcp-server/docs