内容
# aaPanel MCP 服务器
用于 aaPanel 管理的全功能 MCP（模型上下文协议）服务器。提供 **278 个工具**，涵盖 19 个模块，涵盖所有主要的 aaPanel 功能：系统、站点、数据库、FTP、文件、防火墙、定时任务、SSL、配置、插件、Docker、项目、日志、SSH、备份、监控、部署、**系统优化**（RAM 清理、CPU 调优、存储管理、WAF、PHP/Nginx/Apache 优化）和 **安全**（网络扫描、网站统计、篡改防护、系统强化、病毒扫描、CVE 扫描、防盗链）。
## aaPanel 版本兼容性
**已针对 aaPanel v8.0.4 进行测试**（Ubuntu 24.04、Nginx 1.30、MySQL 8.0、PHP 8.3）
> **重要：** aaPanel API 端点可能会在面板版本之间发生变化。如果在更新 aaPanel 后遇到 404 错误或意外响应，则可能需要更新 `aapanel_mcp/tools/*.py` 中的端点映射。有关如何修复端点的详细信息，请参阅 [贡献](#contributing)。
| aaPanel 版本 | 状态 | 说明 |
|--------------|--------|-------|
| 8.0.4 | ✅ 已测试 | 所有端点已于 2026 年 7 月验证 |
| 8.x | ⚠️ 可能有效 | 如果端点发生变化，请报告问题 |
| 7.x | ❓ 未测试 | 可能需要更新端点 |
## 功能
- **278 个 MCP 工具**，涵盖 19 个模块
- **多服务器支持** — 从一个 MCP 服务器管理多个 aaPanel 实例
- **完整的 API 覆盖** — 网站、数据库、FTP、文件、防火墙、定时任务、SSL、Docker、项目等
- **系统优化** — RAM 清理、CPU 调优、存储管理、WAF、安全基准扫描、PHP/Nginx/Apache 配置优化
- **安全** — 网络扫描、网站统计、篡改防护、系统强化（SSH、2FA、IP 白名单）、病毒/恶意软件扫描、CVE 漏洞扫描、防盗链、流量限制、警报配置
- **安全防护** — 内置保护，防止意外删除关键资源
- **基于令牌的身份验证** — 使用 aaPanel 的原生 API 令牌机制
- **重试和退避** — 出现暂时性错误时重试 2 次，延迟 1s/2s
- **stdio 传输** — 与 Windsurf、Cursor、Claude Desktop 等 MCP 客户端集成
## 快速入门
### 选项 A — pip / uvx（推荐 Python 用户）
```bash
pip install aapanel-mcp
```
或在不安装的情况下立即运行：
```bash
uvx aapanel-mcp
```
### 选项 B — 独立二进制文件（不需要 Python）
从 [最新版本](https://github.com/nipunanirmal/aapanel-mcp/releases/latest)下载适用于您平台的存档：
| 平台 | 文件 |
|----------|------|
| Linux x64 | `aapanel-mcp-linux-x64.tar.gz` |
| macOS | `aapanel-mcp-macos.tar.gz` |
| Windows | `aapanel-mcp-windows.zip` |
解压并运行：
```bash
# Linux / macOS
tar -xzf aapanel-mcp-linux-x64.tar.gz
./aapanel-mcp/aapanel-mcp
# Windows
Expand-Archive aapanel-mcp-windows.zip
.\aapanel-mcp\aapanel-mcp.exe
```
### 选项 C — 从源代码
```bash
git clone https://github.com/nipunanirmal/aapanel-mcp.git
cd aapanel-mcp
pip install -r requirements.txt
python main.py
```
### 配置服务器
创建 `~/.aapanel-mcp/servers.yaml`（或设置 `AAPANEL_CONFIG_PATH`）：
```bash
mkdir -p ~/.aapanel-mcp
cat > ~/.aapanel-mcp/servers.yaml << 'EOF'
servers:
- name: "prod-01"
host: "http://192.168.1.100:8888"
token: "YOUR_API_TOKEN"
verify_ssl: false
timeout: 30
global:
default_server: "prod-01"
EOF
```
**获取您的 API 令牌：**
1. 登录 aaPanel
2. 进入 **设置** → **API 接口**
3. 启用 API 接口
4. 复制 API 令牌
### 在 MCP 客户端中配置
**Windsurf** — 添加到 MCP 设置：
```json
{
"mcpServers": {
"aapanel": {
"command": "aapanel-mcp",
"env": {
"AAPANEL_CONFIG_PATH": "/path/to/servers.yaml"
}
}
}
}
```
**Cursor** — 添加到 `~/.cursor/mcp.json`：
```json
{
"mcpServers": {
"aapanel": {
"command": "aapanel-mcp",
"env": {
"AAPANEL_CONFIG_PATH": "/path/to/servers.yaml"
}
}
}
}
```
**Claude Desktop** — 添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"aapanel": {
"command": "aapanel-mcp",
"env": {
"AAPANEL_CONFIG_PATH": "/path/to/servers.yaml"
}
}
}
}
```
> **使用独立二进制文件？** 将 `"command": "aapanel-mcp"` 替换为提取的二进制文件的路径，例如 `"command": "/path/to/aapanel-mcp/aapanel-mcp"`。
## 可选的 aaPanel 终端桥
`terminal_execute_command` 需要可选的 **aaPanel 终端桥** 插件，只有在使用终端中的 aaPanel 主机保存的 MCP 运行命令时才需要。 aaPanel 终端通常使用经过身份验证的浏览器 WebSocket；MCP 客户端使用 aaPanel API 令牌代替。 桥接器在 aaPanel 内运行，验证现有的 API 令牌签名，并重用仅在 aaPanel 终端中保存的主机。
MCP 服务器默认不会在您的计算机或 aaPanel 服务器上安装此插件。 使用 `terminal_bridge_status` 检查状态。 如果它丢失，`terminal_install_bridge` 首先会解释为什么需要它并显示 GitHub Release 下载 URL。 它只会在您再次调用并使用 `confirmed=true` 时下载并导入发布 ZIP 文件。
发布资产：`mcp_terminal.zip`
## 工具类别
| 类别 | 工具 | 说明 |
|----------|-------|-------------|
| 系统 | 12 | CPU、内存、磁盘、网络、服务管理 |
| 站点 | 20 | 创建、删除、SSL、重定向、代理、域名、备份 |
| 数据库 | 12 | MySQL/PostgreSQL 数据库、备份、日志 |
| FTP | 5 | FTP 用户管理 |
| 文件 | 15 | 文件操作（读取、写入、mkdir、压缩等） |
| 防火墙 | 8 | 端口和 IP 规则、面板端口 |
| Crontab | 7 | Cron 作业管理 |
| SSL | 8 | 证书管理、Let's Encrypt |
| 面板配置 | 15 | 面板设置、用户、身份验证、API 配置 |
| 插件 | 8 | 软件/插件安装、配置 |
| Docker | 10 | 容器、镜像、网络、卷管理 |
| 项目 | 8 | Java/Node/Go/Python/.NET/代理/HTML 项目 |
| 日志 | 8 | 面板、安全、错误、Nginx、Apache、Redis 日志 |
| SSH | 4 | SSH 配置、日志、安全审计 |
| 备份/任务 | 6 | 备份管理、后台任务 |
| 监控 | 5 | 实时和历史监控 |
| 部署 | 3 | 一键部署包 |
| 优化 | 68 | RAM 清理、CPU 调优、存储管理、WAF、安全基准、PHP/Nginx/Apache 配置、进程管理、异常检测、软件安装 |
| 安全 | 62 | 网络扫描、网站统计、篡改防护、系统强化（SSH/2FA/IP 白名单）、病毒/恶意软件扫描、CVE 扫描、防盗链、流量限制、警报、操作日志 |
## 安全规则
MCP 服务器具有内置的**安全防护**，保护关键的 aaPanel 资源免受意外或未经授权的删除。 这在 API 客户端级别强制执行 - 没有任何工具可以绕过它。
### 永久阻止（永远不允许，即使确认）
- **删除关键路径中的文件**： `/www/server/panel`、`/www/server/data`、`/www/server/mysql`、`/www/server/nginx`、`/www/server/apache`、`/www/server/php`、`/www/server/docker`、`/www/wwwroot`、`/www/backup`、`/www/database`、`/root`、`/etc`、`/var/lib/mysql`、`/var/lib/docker`、`/var/lib/redis`、`/var/lib/postgresql`、`/boot`、`/proc`、`/sys`、`/dev`
- **删除系统数据库**： `mysql`、 `information_schema`、 `performance_schema`、 `sys`、 `postgres`、 `template0`、 `template1`
### 需要明确用户确认
AI 助手**必须在执行任何这些操作之前征求您的许可**。即使您在聊天中请求删除，AI 也会提示您确认：
- **数据库**： `DeleteDatabase`、 `DelBackup`
- **Docker**： `StopContainer`、 `DeleteImage`、 `DeleteVolume`、 `DeleteNetwork`
- **站点**： `DeleteSite`、 `SiteStop`、 `DelDomain`
- **文件**： `DeleteFile`（在受保护的路径之外）
- **FTP**： `DeleteUser`
- **防火墙**： `DelAcceptPort`、 `DelDropAddress`
- **Crontab**： `DelCrontab`
- **SSL**： `RemoveCert`
- **插件**： `uninstall_plugin`
- **软件**： `UninstallSoft`
- **系统**： `KillProcess`、 `ClearSystem`、 `RestartServer`
- **面板**： `ClosePanel`
- **任务**： `remove_task`
- **SSH**： `stop_password`、 `stop_root`、 `stop_key`、 `stop_jian`
- **篡改**： `del_file_deny`
- **会话**： `DelOldSession`
- **清理**： `CloseLogs`、 `clean_panel_error_logs`、 `clear_temp_login`、 `ReMemory`、 `ReWeb`、 `RepPanel`
### 工作原理
1. 每个 API 请求都通过 `check_request_safety()`，然后再发送到 aaPanel
2. 被阻止的操作返回 `{"status": false, "blocked_by_safety": true}`，并附有说明
3. 未确认的破坏性操作返回 `{"status": false, "confirmation_required": true}` - AI 必须要求您确认
4. 只读操作（get、list、status）无需任何限制即可通过
## 多服务器使用
所有工具都接受可选的 `server` 参数，以针对特定的面板：
```python
# 使用默认服务器
system_get_status()
# 目标特定服务器
system_get_status(server="staging-01")
```
## 配置参考
| 字段 | 必需 | 默认值 | 说明 |
|-------|----------|---------|-------------|
| `name` | 是 | - | 服务器标识符 |
| `host` | 是 | - | 面板 URL（例如 `http://ip:8888`） |
| `token` | 是 | - | 面板设置中的 API 令牌 |
| `verify_ssl` | 否 | `false` | 验证 SSL 证书 |
| `timeout` | 否 | `30` | 请求超时（秒） |
## 身份验证
MCP 服务器使用 aaPanel 的原生 API 令牌机制：
```
request_token = md5(request_time + md5(api_token))
```
这作为查询参数发送到每个 API 请求中。不需要会话 cookie 或登录流程。
## 项目结构
```
aapanel-mcp/
├── main.py # 入口点
├── requirements.txt
├── pyproject.toml
├── LICENSE
├── .gitignore
├── config/
│ ├── servers.yaml.example # 示例配置（可以提交）
│ └── servers.yaml # 您的实际配置（gitignored）
└── aapanel_mcp/
├── __init__.py
├── main.py # 主入口
├── server.py # MCP 服务器设置
├── client.py # aaPanel API 客户端（重试、超时、身份验证）
├── config.py # 配置管理
├── safety.py # 操作的安全防护
├── utils/
│ └── __init__.py # 实用函数（format_response）
└── tools/
├── system.py # 系统工具（12）
├── sites.py # 站点工具（20）
├── databases.py # 数据库工具（12）
├── ftp.py # FTP 工具（5）
├── files.py # 文件工具（15）
├── firewall.py # 防火墙工具（8）
├── crontab.py # Crontab 工具（7）
├── ssl.py # SSL 工具（8）
├── panel_config.py # 配置工具（15）
├── plugins.py # 插件工具（8）
├── docker.py # Docker 工具（10）
├── projects.py # 项目工具（8）
├── logs.py # 日志工具（8）
├── ssh.py # SSH 工具（4）
├── backup.py # 备份/任务工具（6）
├── monitoring.py # 监控工具（5）
├── deployment.py # 部署工具（3）
├── optimization.py # 优化工具（68）
└── security.py # 安全工具（62）
```
## 贡献
欢迎贡献！ aaPanel 更新可能会更改 API 端点，因此社区帮助保持该项目更新是值得赞赏的。
### 如何修复损坏的端点
如果在 aaPanel 更新后某个工具返回 404 错误或意外响应：
1. **查找损坏的工具** - 检查哪个工具返回了错误以及它位于哪个文件（`aapanel_mcp/tools/*.py`）
2. **查找正确的端点** - 打开 aaPanel 的 Web UI，使用浏览器 DevTools（网络选项卡）查看 UI 调用哪个 API 端点以执行相同的操作
3. **更新端点** - 编辑工具文件中相应的 `client.request("/path?action=ActionName", params)` 调用
4. **测试** - 重启 MCP 服务器并调用工具以验证
5. **提交 PR** - 附上类似“修复工具 X 的端点（aaPanel v8.x）”的描述
### 常见端点模式
aaPanel 使用一些一致的模式：
| 模式 | 示例 | 用于 |
|---------|---------|----------|
| `/data?action=getData&table=X` | `/data?action=getData&table=sites` | 列表数据（站点、数据库、防火墙等） |
| `/module?action=ActionName` | `/database?action=AddDatabase` | 模块特定操作 |
| `/config?action=get_config` | `/config?action=get_config` | 面板配置 |
| `/plugin?action=a` | `/plugin?action=a` | 插件操作 |
| `/ajax?action=GetX` | `/ajax?action=GetNginxStatus` | 实时状态/监控 |
| `/system?action=GetX` | `/system?action=GetNetWork` | 系统信息 |
### 开发设置
```bash
git clone https://github.com/nipunanirmal/aapanel-mcp.git
cd aapanel-mcp
pip install -r requirements.txt
cp config/servers.yaml.example config/servers.yaml
# 使用您的面板详细信息编辑 servers.yaml
python main.py
```
### 构建独立二进制文件
```bash
pip install pyinstaller
pyinstaller aapanel_mcp.spec
# 二进制文件位于 dist/aapanel-mcp/aapanel-mcp
```
### 指南
- 保持更改最小和聚焦
- 在提交前针对真实的 aaPanel 实例进行测试
- 如果您针对新版本的 aaPanel 进行测试，请更新此 README 中的版本兼容性表
- 不要提交实际凭证（servers.yaml 被 gitignored）
## 使用的开发工具
该项目使用 **GLM 5.2 HIGH**（Zhipu AI）作为编码助手，并针对 live aaPanel v8.0.4 实例测试了所有端点。
## 许可证
MIT - 参见 [LICENSE](LICENSE)
