aaPanel MCP Server

Full-featured MCP (Model Context Protocol) server for aaPanel management. Provides 282 tools across 19 modules covering all major aaPanel functionality: system, sites, databases, FTP, files, firewall, crontab, SSL, config, plugins, Docker, projects, logs, SSH, backups, monitoring, deployment, system optimization (RAM cleanup, CPU tuning, storage management, WAF, PHP/Nginx/Apache optimization), and security (network scan, website statistics, tamper proof, system hardening, virus scan, CVE scanning, anti-theft).

aaPanel Version Compatibility

Tested against aaPanel v8.0.7 (Ubuntu 24.04, Nginx 1.30, MySQL 8.0, PHP 8.3)

Important: aaPanel API endpoints may change between panel versions. If you encounter 404 errors or unexpected responses after updating aaPanel, the endpoint mappings in aapanel_mcp/tools/*.py may need to be updated. See Contributing for details on how to fix endpoints.

Backward compatibility: tools that use v8.0.7-only routes (e.g. /v2/btdocker/*, /v2/ssl_domain, /v2/safe/*, /v2/site_monitor, /warning) automatically fall back to the equivalent legacy v1 endpoint when the panel reports the route as missing. Both new and old panels are supported by the same tool surface.

Optional module dependencies

Some tools depend on optional aaPanel plugins or modules that may not be installed on your panel. They return a clear error (not a crash) when the module is absent:

Features

• 282 MCP tools across 19 modules
• Multi-server support — manage multiple aaPanel instances from one MCP server
• Full API coverage — websites, databases, FTP, files, firewall, cron, SSL, Docker, projects, and more
• System optimization — RAM cleanup, CPU tuning, storage management, WAF, security baseline scanning, PHP/Nginx/Apache config optimization
• Security — network scanning, website statistics, tamper proof (file integrity), system hardening (SSH, 2FA, IP whitelist), virus/malware scan, CVE vulnerability scanning, anti-theft/hotlink protection, traffic limiting, alert configuration
• Safety guard — built-in protection against accidental deletion of critical resources
• Token-based authentication — uses aaPanel's native API token mechanism
• Retry with backoff — 2 retries with 1s/2s delays for transient errors
• stdio transport — integrates with Windsurf, Cursor, Claude Desktop, and other MCP clients

Quick Start

Option A — pip / uvx (recommended for Python users)

pip install aapanel-mcp

Or run instantly without installing:

uvx aapanel-mcp

Option B — Standalone binary (no Python required)

Download the archive for your platform from the latest release:

Extract and run:

# 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

Option C — From source

git clone https://github.com/nipunanirmal/aapanel-mcp.git
cd aapanel-mcp
pip install -r requirements.txt
python main.py

Configure servers

Create ~/.aapanel-mcp/servers.yaml (or set AAPANEL_CONFIG_PATH):

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

To get your API token:

1. Log in to aaPanel
2. Go to Settings → API Interface
3. Enable API interface
4. Copy the API token

Configure in MCP clients

Windsurf — add to MCP settings:

{
  "mcpServers": {
    "aapanel": {
      "command": "aapanel-mcp",
      "env": {
        "AAPANEL_CONFIG_PATH": "/path/to/servers.yaml"
      }
    }
  }
}

Cursor — add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "aapanel": {
      "command": "aapanel-mcp",
      "env": {
        "AAPANEL_CONFIG_PATH": "/path/to/servers.yaml"
      }
    }
  }
}

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "aapanel": {
      "command": "aapanel-mcp",
      "env": {
        "AAPANEL_CONFIG_PATH": "/path/to/servers.yaml"
      }
    }
  }
}

Using the standalone binary? Replace "command": "aapanel-mcp" with the path to the extracted binary, e.g. "command": "/path/to/aapanel-mcp/aapanel-mcp".

Optional aaPanel Terminal Bridge

terminal_execute_command needs the optional aaPanel Terminal Bridge plugin only when you want MCP to run commands through aaPanel hosts saved in Terminal. aaPanel Terminal normally uses an authenticated browser WebSocket; an MCP client uses the aaPanel API token instead. The bridge runs inside aaPanel, validates the existing API-token signature, and reuses only hosts already saved in aaPanel Terminal.

The MCP server never installs this plugin on your computer or on an aaPanel server by default. Use terminal_bridge_status to inspect the state. If it is missing, terminal_install_bridge first explains why it is needed and shows the GitHub Release download URL. It downloads and imports the release ZIP only after you call it again with confirmed=true.

Release asset: mcp_terminal.zip

Tool Categories

Safety Rules

The MCP server has a built-in safety guard that protects critical aaPanel resources from accidental or unauthorized deletion. This is enforced at the API client level — no tool can bypass it.

Permanently Blocked (never allowed, even with confirmation)

• Deleting files in critical paths: /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
• Deleting system databases: mysql, information_schema, performance_schema, sys, postgres, template0, template1

Requires Explicit User Confirmation

The AI assistant must ask for your permission before executing any of these actions. Even if you request deletion in chat, the AI will prompt you to confirm before proceeding:

• Databases: DeleteDatabase, DelBackup
• Docker: StopContainer, DeleteImage, DeleteVolume, DeleteNetwork
• Sites: DeleteSite, SiteStop, DelDomain
• Files: DeleteFile (outside protected paths)
• FTP: DeleteUser
• Firewall: DelAcceptPort, DelDropAddress
• Crontab: DelCrontab
• SSL: RemoveCert
• Plugins: uninstall_plugin
• Software: UninstallSoft
• System: KillProcess, ClearSystem, RestartServer
• Panel: ClosePanel
• Tasks: remove_task
• SSH: stop_password, stop_root, stop_key, stop_jian
• Tamper: del_file_deny
• Sessions: DelOldSession
• Cleanup: CloseLogs, clean_panel_error_logs, clear_temp_login, ReMemory, ReWeb, RepPanel

How It Works

1. Every API request passes through check_request_safety() before being sent to aaPanel
2. Blocked operations return {"status": false, "blocked_by_safety": true} with an explanation
3. Unconfirmed destructive operations return {"status": false, "confirmation_required": true} — the AI must ask you to confirm
4. Read-only operations (get, list, status) pass through without any restriction

Multi-Server Usage

All tools accept an optional server parameter to target a specific panel:

# Use default server
system_get_status()

# Target a specific server
system_get_status(server="staging-01")

Configuration Reference

Authentication

The MCP server uses aaPanel's native API token mechanism:

request_token = md5(request_time + md5(api_token))

This is sent as query parameters with each API request. No session cookies or login flows are needed.

Project Structure

aapanel-mcp/
├── main.py                     # Entry point
├── requirements.txt
├── pyproject.toml
├── LICENSE
├── .gitignore
├── config/
│   ├── servers.yaml.example    # Example configuration (safe to commit)
│   └── servers.yaml            # Your actual config (gitignored)
└── aapanel_mcp/
    ├── __init__.py
    ├── main.py                 # Main entry
    ├── server.py               # MCP server setup
    ├── client.py               # aaPanel API client (retry, timeout, auth)
    ├── config.py               # Configuration management
    ├── safety.py               # Safety guard for destructive operations
    ├── utils/
    │   └── __init__.py         # Utility functions (format_response)
    └── tools/
        ├── system.py           # System tools (12)
        ├── sites.py            # Site tools (19)
        ├── databases.py        # Database tools (12)
        ├── ftp.py              # FTP tools (5)
        ├── files.py            # File tools (15)
        ├── firewall.py         # Firewall tools (8)
        ├── crontab.py          # Crontab tools (7)
        ├── ssl.py              # SSL tools (8)
        ├── panel_config.py     # Config tools (14)
        ├── plugins.py          # Plugin tools (8)
        ├── docker.py           # Docker tools (10)
        ├── projects.py         # Project tools (8)
        ├── logs.py             # Log tools (8)
        ├── ssh.py              # SSH tools (4)
        ├── backup.py           # Backup/task tools (6)
        ├── monitoring.py       # Monitoring tools (5)
        ├── deployment.py       # Deployment tools (3)
        ├── optimization.py     # Optimization tools (67)
        └── security.py         # Security tools (59)

Contributing

Contributions are welcome! aaPanel updates may change API endpoints, so community help keeping this project up-to-date is greatly appreciated.

How to Fix Broken Endpoints

If a tool returns a 404 error or unexpected response after an aaPanel update:

1. Find the broken tool — check which tool returned the error and which file it's in (aapanel_mcp/tools/*.py)
2. Find the correct endpoint — open aaPanel's web UI, use browser DevTools (Network tab) to see which API endpoint the UI calls for the same action
3. Update the endpoint — edit the corresponding client.request("/path?action=ActionName", params) call in the tool file
4. Test — restart the MCP server and call the tool to verify
5. Submit a PR — with a description like "Fix endpoint for tool X (aaPanel v8.x)"

Common Endpoint Patterns

aaPanel uses a few consistent patterns:

Development Setup

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
# Edit servers.yaml with your panel details
python main.py

Building Standalone Binaries

pip install pyinstaller
pyinstaller aapanel_mcp.spec
# Binary is in dist/aapanel-mcp/aapanel-mcp

Guidelines

• Keep changes minimal and focused
• Test against a real aaPanel instance before submitting
• Update the version compatibility table in this README if you test against a new aaPanel version
• Don't commit real credentials (servers.yaml is gitignored)

Developed Using

This project was developed using GLM 5.2 HIGH (Zhipu AI) as the coding assistant, with all endpoints tested against a live aaPanel v8.0.4 instance. The v8.0.7 compatibility audit and endpoint fixes were performed with Devin (Cognition AI).

License

MIT — see LICENSE