fastpanel-mcp

Talk to your FastPanel 2 server from Claude, Cursor, or any MCP-compatible client. Create sites, provision databases, attach SSL, harden nginx configs — through natural language, with production-grade safety rails.

Keywords: FastPanel, MCP, Model Context Protocol, Claude Code, Claude Desktop, server management, hosting automation, nginx, Let's Encrypt, DevOps, LLM ops, AI sysadmin.

Read this in other languages: English · Русский · Українська · Español · Deutsch

---

What you get

Ask an LLM, get real infra changes on your FastPanel server:

You: "Create a new site foo.example.com under user www-root, PHP 8.4, no database, and attach our wildcard SSL cert. Also enable HTTP/2 and HTTP/3."

LLM (~30 seconds, 5 tool calls later): Site id 53 is live at https://foo.example.com with HTTP/2, HTTP/3, wildcard TLS, and an auto-provisioned HTTPS redirect.

You: "Show me the nginx config for site 1 — check if it blocks .env, .git, and other sensitive paths. If not, add hardening."

LLM: Reads the config, notes that .env and .htaccess are served as static files (security gap), edits the frontend to add deny rules for dotfiles + sensitive extensions + framework files, previews the diff via dry_run, then deploys it. .env now returns 404; .well-known/acme-challenge still works.

You: "What sites are running on this server, who owns them, and which ones don't force HTTPS?"

LLM: Queries sites_list and reports the 5 sites without https_redirect: true.

Features

• 32 tools covering sites, databases (incl. SSH dump/import), users, DNS zones, SSL certificates, system load, queue, site logs, backup plans, host-level diagnostics, file upload/deploy into a site's web root, and raw nginx/apache/php.ini configs.
• Dual-token safety model. Read operations use a read-only token; mutating operations require a separate write token (FASTPANEL_WRITE_TOKEN). Unset the write token and every write tool fails closed.
• confirm: true required on every write. Accidental LLM outputs cannot mutate state.
• dry_run: true previews the exact HTTP body the server would receive — passwords redacted as ***, no network call fired.
• Compact response mode on sites_list to avoid overflowing LLM context on large panels.
• stderr audit log for every executed write, with passwords redacted.
• MCP tool annotations (readOnlyHint / destructiveHint / idempotentHint / openWorldHint) so clients and policy scanners classify each tool correctly instead of treating read-only diagnostics as destructive.
• nginx -t auto-validation with rollback — site_configuration_update validates the live config after applying and reverts a broken edit automatically when SSH is configured.
• Tested against a live FastPanel 2 panel with 35+ sites in production.

Why this exists

FastPanel publishes no OpenAPI spec. The endpoints and payload shapes in this server were reverse-engineered from the panel's Angular SPA bundle and live DevTools captures, including non-obvious quirks like:

• List endpoints require filter[limit]=…&filter[type]=… wrapped params — bare ?limit=… is silently ignored.
• Site creation is a two-step wizard (POST /api/master/domain probe → PUT /api/master), not a conventional POST /api/sites.
• The backend field in site configuration is PHP-FPM pool config when handler=php_fpm, but an Apache VirtualHost block when handler=fcgi.
• SSL attach/detach flows through PUT /api/sites/{id} (site-side) not POST /api/sites/{id}/certificate (there is no such endpoint).

These are documented in the tool descriptions so the LLM doesn't have to rediscover them.

Requirements

• Node.js 20 or newer
• A FastPanel 2 installation reachable over HTTPS
• Root SSH on the panel host to create API tokens (one-time)

Install

git clone https://github.com/iMateo/fastpanel-mcp.git
cd fastpanel-mcp
pnpm install      # or: npm install
pnpm build

Get API tokens

On the FastPanel host (as root), create a read-only token for day-to-day use:

mogwai users tokens add -n mcp-read -s read_only -e 2030-12-31

The CLI binary is /usr/local/fastpanel2/fastpanel; recent FastPanel builds expose it on PATH as mogwai (/usr/local/bin/mogwai → the same binary). Older docs call it fastpanel, which is not on PATH — use mogwai, or the full path. Root only.

Copy the msg field from the returned JSON — that's your token. It bypasses 2FA and survives session TTLs, so treat it as a server credential.

Optional write token, with an expiry and IP lock:

mogwai users tokens add -n mcp-write -c <your-ip> -e 2030-12-31

Leave FASTPANEL_WRITE_TOKEN unset in configs where you don't need writes.

Configure

cp .env.example .env

Minimum viable .env:

FASTPANEL_URL=https://panel.example.com:8888
FASTPANEL_TOKEN=<your read token>
FASTPANEL_INSECURE_TLS=1   # only if panel uses self-signed cert

Use with Claude Code

claude mcp add fastpanel \
  -s user \
  -e "FASTPANEL_URL=https://panel.example.com:8888" \
  -e "FASTPANEL_TOKEN=…" \
  -e "FASTPANEL_INSECURE_TLS=1" \
  -- node $PWD/dist/index.js

Add -e "FASTPANEL_WRITE_TOKEN=…" when you want write tools enabled.

Use with Claude Desktop / Cursor / other MCP clients

claude_desktop_config.json (or equivalent):

{
  "mcpServers": {
    "fastpanel": {
      "command": "node",
      "args": ["/absolute/path/to/fastpanel-mcp/dist/index.js"],
      "env": {
        "FASTPANEL_URL": "https://panel.example.com:8888",
        "FASTPANEL_TOKEN": "…",
        "FASTPANEL_INSECURE_TLS": "1"
      }
    }
  }
}

Debug

Inspect tools with the MCP Inspector GUI:

pnpm inspect

Drive JSON-RPC over stdio manually:

FASTPANEL_URL=… FASTPANEL_TOKEN=… node scripts/smoke.mjs

Tools

Read (no write token required)

| Tool | Endpoint | Returns | |---|---|---| | sites_list | GET /api/sites/list | All websites, 13 essential fields by default (compact mode) | | site_get | GET /api/sites/{id} | Full 40-field site object (cert, backend, backups, stats) | | site_configuration_get | GET /api/sites/{id}/configuration | Raw nginx (frontend), handler backend (PHP-FPM or Apache), php.ini | | databases_list | GET /api/databases | MySQL + PostgreSQL databases with owners and sizes | | database_servers_list | GET /api/databases/servers | Available DB servers — use ids in database_create | | users_list | GET /api/users | Panel users and site owners | | dns_domains_list | GET /api/dns/domains | DNS zones (empty if panel DNS is off) | | dns_records_list | GET /api/dns/domain/{id}/records | Records for one zone | | certificates_list | GET /api/certificates | Stored SSL certificates (LE + custom) | | system_load | GET /api/loads/full | CPU / memory / disk / load averages / top processes | | queue_list | GET /api/queue/list | Background tasks including completed | | queue_active | GET /api/queue | In-flight tasks only (filters finished) + meta.all_done for deterministic polling | | site_logs | GET /api/sites/{id}/log/{lines}/{type} | Tail nginx/apache access or error log (frontend_/backend_) without SSH | | site_resources | GET /api/sites/{id}/resources | Databases, sub-domains, DNS & email zones attached to a site | | backup_plans_list | GET /api/v2/backup/plans | Configured backup plans | | me | GET /api/me | Account behind the current read token (username, roles, ssh) | | settings_get | GET /api/settings | Panel-wide settings (OS, license, limits, notifications) |

Write (require FASTPANEL_WRITE_TOKEN + explicit confirm: true)

| Tool | Endpoint | Purpose | |---|---|---| | user_create | POST /api/users | Create a new panel user (site owner) | | database_create | POST /api/databases | Create MySQL or PostgreSQL database with a dedicated DB user | | site_create | POST /api/master/domain + PUT /api/master | Create a site atomically, optionally with inline user / database / FTP | | site_update | PUT /api/sites/{id} | Change document root (index_dir) / directory index — e.g. point a Laravel site at public/ (framework: "laravel" preset) | | site_ssl_update | PUT /api/sites/{id} | Attach / replace / detach an SSL certificate, toggle HTTPS / HTTP2 / HTTP3 / HSTS | | site_backend_update | PUT /api/sites/backend/{backend_id} | Change PHP version, handler, port, socket, env vars (pass site id — backend id resolved internally) | | site_configuration_update | PUT /api/sites/{id}/configuration | Replace raw nginx/apache/php.ini for the site. Dangerous: bad syntax can break the site — when SSH is configured, runs nginx -t after applying and auto-reverts on failure (validate: false to skip) | | certificate_create_letsencrypt | POST /api/certificates | Issue a new Let's Encrypt certificate (async — poll queue_active) |

SSH-backed (require FASTPANEL_SSH_HOST)

These do what the REST API can't — they run on the panel host itself. Opt-in and host-agnostic: set FASTPANEL_SSH_HOST (+ optional FASTPANEL_SSH_USER/PORT/KEY) to point at any FastPanel server. The server shells out to your own ssh client, so the host just needs to be reachable with key-based auth. nginx_validate and site_doctor are read-only; the rest are writes (confirm: true + dry_run preview).

| Tool | Runs | Purpose | |---|---|---| | nginx_validate | nginx -t | Validate the live nginx config before/after site_configuration_update — catch syntax errors before they take nginx down | | site_doctor | stat / systemctl / nginx -t | Diagnose why a site errors: missing docroot, a parent dir without o+x (the 750 → 404 trap), missing FPM socket, dead backend, broken nginx config | | database_dump | mysqldump | Dump a database to a .sql file in the staging dir (local MySQL). Writes a root-owned file — needs confirm: true | | database_import | mysql | Load a .sql file (from the staging dir) into a database. Destructive — needs confirm: true | | site_files_upload | rsync (scp fallback) | Upload a local file/dir into a site's web root, then chown to the site user. delete: true mirrors (removes remote-only files) | | site_files_deploy | git clone / curl + tar | Fetch files on the host (https git repo or tarball) into a site's web root, then chown to the site user | | site_file_put | cat over ssh | Write one small inline file (placeholder/.htaccess/robots.txt) into a site's web root, then chown to the site user |

Dump/import paths are confined to a staging dir (default /root/fastpanel-mcp-dumps, override with FASTPANEL_DUMP_DIR); paths outside it or containing .. are rejected. The three upload/deploy tools resolve the site's index_dir + owner via site_get, refuse destination subpaths that escape the web root or contain shell-unsafe characters, and chown everything to the site's system user so nginx/PHP-FPM can serve it (root-owned files would 403).

Cookbook

Provision a new test site under a wildcard cert (30 seconds, no DNS/LE wait):

site_create(domain="foo.example.com", owner_id=2, php_version="84")
  → site_ssl_update(site_id=<new>, certificate_id=<wildcard>, https_redirect=true, http2=true, http3=true)

Provision a production site with a fresh Let's Encrypt cert:

site_create(domain="foo.com", aliases=["