# mcp-ssh-server

**Repository Path**: yadong_C/mcp-ssh-server

## Basic Information

- **Project Name**: mcp-ssh-server
- **Description**: 通过MCP调用ssh来管理服务器，带有一个配置管理前端。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-12
- **Last Updated**: 2025-08-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP SSH工具

一个基于MCP（Model Context Protocol）的SSH管理工具，允许通过自然语言直接管理云服务器。同时提供Web界面进行可视化操作。

## 🚀 功能特性

- **服务器管理**: 添加、删除、查看服务器配置
- **SSH命令执行**: 在指定服务器上执行命令
- **连接测试**: 测试SSH连接状态
- **MCP协议**: 完全符合MCP协议规范，支持Cursor等IDE
- **中文支持**: 修复了编码问题，完美支持中文
- **Web界面**: 提供现代化的Web界面进行可视化操作

## 📋 可用的MCP工具

1. **list_servers** - 列出所有配置的服务器
2. **execute_command** - 在指定服务器上执行SSH命令
3. **add_server** - 添加新的服务器配置
4. **delete_server** - 删除服务器配置
5. **get_server_info** - 获取指定服务器的详细信息
6. **test_connection** - 测试与指定服务器的SSH连接

## 🔧 安装和配置

### 前置要求

- **Python 3.7+** (MCP服务)
- **Node.js 14.0+** (Web界面)
- 必要的Python包：`paramiko`, `cryptography`

### 安装依赖

#### Python依赖
```bash
pip install paramiko cryptography
```

#### Node.js依赖
```bash
npm install
```

## 🚀 启动服务

### 启动Web界面

#### Windows用户
```bash
start_web.bat
```

#### 手动启动
```bash
npm start
```

Web界面将在 http://localhost:3000 启动

### 启动MCP服务

在Cursor中配置MCP服务（见下文）

## 🔧 在Cursor中配置MCP服务

#### 方法1: 直接配置（推荐）

在您的项目中创建或编辑`.cursorrules`文件：

```json
{
  "mcpServers": {
    "ssh-tools": {
      "command": "python",
      "args": ["E:/source/mcp-tools/ssh-tools/mcp/mcp_protocol_server.py"]
    }
  }
}
```

**注意**: 请将路径 `E:/source/mcp-tools/ssh-tools` 替换为您项目的实际路径。

#### 方法2: 使用环境变量

设置环境变量：
```bash
export MCP_SSH_TOOLS_PATH="/path/to/your/project"
```

然后在`.cursorrules`中使用：
```json
{
  "mcpServers": {
    "ssh-tools": {
      "command": "python",
      "args": ["%MCP_SSH_TOOLS_PATH%/mcp/mcp_protocol_server.py"]
    }
  }
}
```

## 💬 使用方法

### MCP自然语言操作

配置完成后，您可以在Cursor中使用自然语言来管理服务器：

- "列出所有服务器"
- "在测试服务器上执行 'ls -la' 命令"
- "添加一个新的生产服务器，IP是10.0.0.1，用户名是root"
- "测试与开发服务器的连接"
- "删除名为'旧服务器'的配置"

### Web界面操作

访问 http://localhost:3000 使用Web界面：

- 添加/删除服务器
- 查看服务器列表
- 测试连接状态
- 执行SSH命令

## 🏗️ 项目结构

```
mcp-tools/ssh-tools/
├── mcp/
│   ├── mcp_protocol_server.py  # MCP协议服务器（主要文件）
│   ├── ssh_server.py           # SSH功能实现
│   ├── __init__.py             # Python包初始化
│   └── requirements.txt        # Python依赖列表
├── public/                     # Web界面文件
│   ├── index.html             # 主页面
│   ├── app.js                 # 前端逻辑
│   └── styles.css             # 样式文件
├── server.js                  # Node.js Web服务器
├── package.json               # Node.js项目配置
├── start_web.bat             # Web界面启动脚本
├── .cursorrules               # Cursor MCP配置示例
├── pyproject.toml            # Python项目配置
├── README.md                 # 项目说明
└── config/                   # 配置文件目录
    └── servers.json          # 服务器配置文件
```

## 🔍 配置文件

### 服务器配置格式

服务器配置存储在 `config/servers.json` 文件中：

```json
{
  "servers": [
    {
      "name": "测试服务器",
      "ip": "192.168.1.100",
      "port": 22,
      "username": "root",
      "auth_type": "password",
      "password": "your_password",
      "description": "本地测试服务器"
    },
    {
      "name": "生产服务器",
      "ip": "10.0.0.1",
      "port": 22,
      "username": "admin",
      "auth_type": "key",
      "key_path": "/path/to/private_key",
      "description": "生产环境服务器"
    }
  ]
}
```

## 🧪 测试

### 测试Web界面

1. **启动Web界面**: 运行 `start_web.bat` 或 `npm start`
2. **访问界面**: 打开 http://localhost:3000
3. **添加服务器**: 使用Web界面添加测试服务器
4. **测试功能**: 尝试连接测试和命令执行

### 测试MCP服务

配置完成后，重启Cursor让MCP配置生效，然后尝试：

1. **列出服务器**: "列出所有服务器"
2. **测试连接**: "测试与测试服务器的连接"
3. **执行命令**: "在测试服务器上执行 'pwd' 命令"

## ⚠️ 注意事项

- 确保Python和Node.js环境已安装必要的依赖
- 服务器配置文件中的敏感信息（如密码）会被隐藏显示
- 支持密码和SSH密钥两种认证方式
- 所有中文内容都经过编码处理，确保正确显示
- Web界面和MCP服务共享同一个配置文件

## 🔧 故障排除

### 常见问题

1. **MCP服务无法连接**
   - 检查Python路径是否正确
   - 确认依赖包已安装
   - 验证配置文件路径

2. **Web界面无法启动**
   - 检查Node.js是否正确安装
   - 确认依赖已安装：`npm install`
   - 检查端口3000是否被占用

3. **中文显示乱码**
   - 当前版本已修复编码问题
   - 如果仍有问题，请检查系统编码设置

4. **SSH连接失败**
   - 检查服务器配置信息
   - 确认网络连接正常
   - 验证认证信息正确

### 获取帮助

如果遇到问题，请检查：
- Python和Node.js版本
- 依赖包安装状态
- 配置文件格式
- 网络连接状态
- 服务器SSH服务状态

## 📚 更多信息

- [MCP协议文档](https://modelcontextprotocol.io/)
- [Cursor MCP支持](https://cursor.sh/docs)
- [Paramiko SSH库](https://www.paramiko.org/)
- [Express.js框架](https://expressjs.com/)

## �� 许可证

本项目采用MIT许可证。