# shell-mcp

**Repository Path**: chenfyu/shell-mcp

## Basic Information

- **Project Name**: shell-mcp
- **Description**: 一个基于 Model Context Protocol (MCP) 的强大Shell接口，支持本地和远程命令执行，带有完善的安全机制和会话管理功能。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-01
- **Last Updated**: 2026-03-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Shell MCP Server

一个基于 Model Context Protocol (MCP) 的强大Shell接口，支持本地和远程命令执行，带有完善的安全机制和会话管理功能。为 AI 智能体提供安全的 Shell 命令执行能力。

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-2024--11--05-orange.svg)](https://modelcontextprotocol.io)

**🌐 [English Documentation](README_EN.md)** | **简体中文文档**

## ✨ 主要功能

- 🖥️ **本地命令执行**: 支持在本地环境执行shell命令
- 🔗 **远程SSH执行**: 支持通过SSH连接到远程服务器执行命令
- 🛡️ **安全防护**: 内置命令黑白名单，防止危险命令执行
- 💾 **会话管理**: 智能会话管理，支持环境变量持久化
- 🌐 **多种传输模式**: 支持stdio和SSE两种传输模式
- 📝 **完整日志**: 详细的日志记录和错误追踪
- ⚡ **异步处理**: 基于asyncio的高性能异步处理

## 🚀 快速开始

### 环境要求

- Python 3.8+
- 支持的操作系统: Windows, Linux, macOS

### 安装

1. **获取代码**

```bash
# 下载源码包并解压到目标目录
cd shell-mcp
```

2. **安装依赖**

```bash
pip install -r requirements.txt
```

3. **配置服务器**

```bash
# 复制配置模板
cp config.json.example config.json
# 编辑配置文件
notepad config.json  # Windows
# 或者使用其他编辑器
```

### 基本使用

1. **Stdio模式 (默认)**

```bash
python shell_mcp_server.py
```

2. **SSE模式**

```bash
# 本地监听
python shell_mcp_server.py --mode sse --port 8000

# 监听所有接口
python shell_mcp_server.py --mode sse --host 0.0.0.0 --port 8000
```

3. **自定义配置文件**

```bash
python shell_mcp_server.py --config my_config.json
```

4. **设置日志级别**

```bash
python shell_mcp_server.py --log-level DEBUG
```

## 📖 配置说明

### config.json 结构

```json
{
  "session_timeout": 1200,
  "command_filter": {
    "blacklist": [
      "^\\s*rm\\s+-rf\\s+/(\\s|$)",
      "^\\s*shutdown",
      "^\\s*reboot"
    ],
    "whitelist": ["ls", "pwd", "echo", "help"]
  },
  "ssh": {
    "default_key_file": "~/.ssh/id_rsa",
    "timeout": 30,
    "max_connections": 10
  },
  "host_mapping": {
    "Linux-Server": {
      "host": "192.168.1.101",
      "username": "admin",
      "key_file": "~/.ssh/id_rsa",
      "port": 22,
      "platform": "linux",
      "description": "Linux服务器"
    },
    "Windows-VMware": {
      "host": "192.168.1.100",
      "username": "your_username",
      "password": "your_password",
      "port": 22,
      "platform": "windows",
      "description": "Windows VMware虚拟机"
    }
  },
  "logging": {
    "level": "INFO",
    "file": "terminal_mcp.log"
  }
}
```

### 安全配置

- **黑名单模式**: 默认禁止危险命令，推荐生产环境使用
- **白名单模式**: 仅允许指定命令，适合高安全要求场景（白名单非空时自动启用，此时只有白名单中的命令可以执行）
- **混合模式**: 黑白名单结合，黑名单优先于白名单检查

## 🔧 MCP工具接口

### execute_command

在本地或远程主机执行命令

**参数:**

- `command` (必需): 要执行的命令
- `os` (必需): 目标操作系统类型，`windows` 或 `linux`
- `host` (可选): 远程主机地址（支持 `host_mapping` 中的名称或 IP 地址，不提供则本地执行）
- `username` (可选): SSH用户名（远程执行时必需，使用主机映射时可省略）
- `password` (可选): SSH密码
- `key_file` (可选): SSH私钥文件路径
- `port` (可选): SSH端口，默认22
- `session` (可选): 会话名称，默认'default'，相同会话名复用SSH连接
- `env` (可选): 环境变量字典
- `cwd` (可选): 本地执行工作目录
- `force_execute` (可选): 强制执行危险命令（跳过删除命令确认，默认false）

**示例:**

```json
{
  "command": "ls -la /home",
  "os": "linux",
  "host": "Linux-Server",
  "session": "my_session"
}
```

### get_tools

获取服务器支持的所有工具列表

### set_host_mapping

动态设置主机名映射，用于远程执行命令

**参数:**

- `host_name` (必需): 主机名称（如 `Windows-VMware`）
- `host_config` (必需): 主机配置对象，包含 `host`、`username`（必需），以及 `password`、`key_file`、`port`、`platform`（可选）

**示例:**

```json
{
  "host_name": "my-server",
  "host_config": {
    "host": "10.0.0.5",
    "username": "admin",
    "key_file": "~/.ssh/id_rsa",
    "port": 22,
    "platform": "linux"
  }
}
```

### list_hosts

列出所有已配置的可用主机及其连接信息（密码等敏感信息已隐藏）

### get_command_filter

查询当前命令过滤规则，包括白名单内容和黑名单分类摘要，帮助了解哪些命令可以执行

## 🌐 SSE模式端点

| 端点 | 方法 | 说明 |
|------|------|------|
| `/message` | GET | 建立SSE连接 |
| `/message` | POST | 发送MCP消息（标准端点） |
| `/mcp` | POST | 发送MCP消息（兼容端点） |
| `/sse` | GET/POST | Cherry Studio 兼容端点 |
| `/mcp/info` | GET | 服务器详细信息 |
| `/.well-known/mcp.json` | GET | MCP 服务发现 |
| `/` | GET | 服务器基本信息 |
| `/reset` | POST/GET | 重置连接状态 |

## 🛡️ 安全注意事项

### ⚠️ 重要安全警告

1. **生产环境使用前请务必**:

   - 修改默认的SSH连接配置
   - 设置强密码或使用SSH密钥认证
   - 配置适合您环境的命令黑白名单
   - 限制网络访问和端口暴露
2. **命令过滤建议**:

   - 优先使用白名单模式
   - 定期审查和更新安全规则
   - 监控命令执行日志
3. **网络安全**:

   - 在防火墙后运行服务
   - 使用VPN或SSH隧道访问
   - 定期更新依赖包

### 默认防护

系统内置了以下危险命令防护:

- 系统删除命令 (`rm -rf /`)
- 文件移动/删除 (`rm`, `mv`, `delete`, `remove`)
- 系统关机重启 (`shutdown`, `reboot`, `halt`, `poweroff`)
- 磁盘格式化 (`mkfs`, `fdisk`, `dd`)
- 用户管理 (`userdel`, `passwd root`)
- 权限修改 (`chmod 777 /`)
- 进程终止 (`killall`, `pkill`, `kill -9`)
- 远程下载执行 (`curl|sh`, `wget|sh`)
- Fork bomb 防护
- 命令串联绕过防护 (`; rm -rf`, `&& rm -rf`)

此外，`rm` 删除命令会触发危险命令确认机制，需要设置 `force_execute=true` 才能执行。

## 🧪 测试示例

### stdio模式测试

```bash
# 启动stdio模式
python shell_mcp_server.py --mode stdio

# 然后逐行输入JSON命令:
# {"jsonrpc":"2.0","method":"initialize","params":{},"id":1}
# {"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}
# {"jsonrpc":"2.0","method":"tools/call","params":{"name":"execute_command","arguments":{"command":"hostname","os":"linux"}},"id":3}
```

### 使用curl测试SSE模式

```bash
# 1. 启动服务器
python shell_mcp_server.py --mode sse --port 8000

# 2. 测试连接
curl http://localhost:8000/mcp/info

# 3. 初始化MCP
curl -X POST http://localhost:8000/message \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

# 4. 获取工具列表
curl -X POST http://localhost:8000/message \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'

# 5. 执行本地命令
curl -X POST http://localhost:8000/message \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"execute_command","arguments":{"command":"hostname","os":"linux"}},"id":3}'

# 6. 查看可用主机
curl -X POST http://localhost:8000/message \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_hosts","arguments":{}},"id":4}'

# 7. 查看命令过滤规则
curl -X POST http://localhost:8000/message \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_command_filter","arguments":{}},"id":5}'
```

### 与Cherry Studio集成

1. 在Cherry Studio中添加MCP服务器
2. 配置端点: `http://localhost:8000/sse`
3. 选择传输模式: SSE
4. 保存并测试连接

## 📚 API文档

详细的API文档请参考:

- [MCP协议规范](https://modelcontextprotocol.io/)

## 🤝 贡献指南

我们欢迎所有形式的贡献！

1. 创建功能分支
2. 提交更改
3. 提交合并请求或联系项目维护者

### 开发环境设置

```bash
# 安装开发依赖
pip install -r requirements.txt

# 代码格式化
black shell_mcp_server.py

# 类型检查
mypy shell_mcp_server.py
```

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

## 🙏 致谢

- [Model Context Protocol](https://modelcontextprotocol.io/) - 协议规范
- [paramiko](https://www.paramiko.org/) - SSH连接库
- [aiohttp](https://aiohttp.readthedocs.io/) - 异步HTTP框架

## 📞 支持

- 🐛 [报告Bug](https://github.com/cnchef/shell-mcp/issues)
- 💡 [功能建议](https://github.com/cnchef/shell-mcp/issues)
- 📖 [文档问题](https://github.com/cnchef/shell-mcp/issues)

## 🗺️ 路线图

- [ ] Web管理界面
- [ ] 更多认证方式支持
- [ ] 命令执行历史记录
- [ ] 集群部署支持
- [ ] 监控和指标收集

## 📚 其他文档

- [英文文档](README_EN.md) - English Documentation
- [架构说明](ARCHITECTURE.md) - 系统架构和设计文档
- [快速开始](QUICKSTART.md) - 5分钟快速上手指南
- [配置指南](docs/configuration.md) - 详细配置说明
- [API文档](docs/api.md) - 接口文档

---

**⚠️ 免责声明**: 本工具主要用于开发和测试目的。在生产环境中使用前，请确保充分了解其安全风险并采取适当的安全措施。