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.

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

• 19 tools covering sites, databases, users, DNS zones, SSL certificates, system load, queue, 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.

• Tested against a live FastPanel 2 panel with 38 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/<you>/fastpanel-mcp.git
cd fastpanel-mcp
pnpm install      # or: npm install
pnpm build

Get API tokens

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

fastpanel users tokens add -n mcp-read -s read_only -e 2026-12-31

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 short expiry and IP lock:

fastpanel users tokens add -n mcp-write -c <your-ip> -e 2026-05-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)

Write (require FASTPANEL_WRITE_TOKEN + explicit confirm: true)

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=["www.foo.com"], owner_id=<id>, php_version="84", database={...})
  → certificate_create_letsencrypt(site_id=<new>, email, common_name="foo.com")
  → queue_active  # poll until LE job SUCCESS

Harden default nginx (block .git, .env, .htaccess, composer.json, etc.):

site_configuration_get(site_id)
  # LLM inserts security location blocks into frontend
site_configuration_update(site_id, frontend=<edited>, backend=<unchanged>, phpini=<unchanged>)

Remove deprecated TLS versions:

site_configuration_get(site_id)
  # LLM replaces "ssl_protocols TLSv1.1 TLSv1.2 TLSv1.3" with "ssl_protocols TLSv1.2 TLSv1.3"
site_configuration_update(site_id, frontend=<edited>, backend=<unchanged>, phpini=<unchanged>)

Safety model

• Dual tokens. Read token always required. Write token is optional — if FASTPANEL_WRITE_TOKEN isn't set, every write tool errors out before touching the network with FastPanelWriteDisabledError.

• confirm: true is a required argument on every write tool. Tools refuse to execute without it — this is your last line of defence against a confused LLM.

• dry_run: true returns the exact JSON body that would be sent, passwords redacted as ***, and skips the HTTP call entirely.

• stderr audit log records every executed write with redacted payload. In Claude Code this surfaces in MCP logs.

• No delete tools yet. Destructive operations are left to the UI until they're deliberately added.

• IP-lock tokens (fastpanel users tokens add -c <ip>) so a leaked token can't be used from elsewhere.

Known gotchas

• filter[...] params: FastPanel list endpoints expect filter[limit]=…&filter[type]=…. Bare ?limit=… is silently ignored.

• Site creation is a wizard, not a REST create. The panel does POST /api/master/domain (probe) then PUT /api/master (actual create), not POST /api/sites. site_create hides this.

• Async operations. Cert issuance, site backend updates, and several other ops return action: "CREATING" / "UPDATING" immediately and run in the background. Use queue_active to poll.

• No official OpenAPI spec. Endpoints were reverse-engineered. If a new FastPanel release breaks something, please file an issue with the new payload shape.

• Self-signed TLS. Most panel installs use self-signed certs. Set FASTPANEL_INSECURE_TLS=1 or put a proper cert in front.

• fail2ban / rate limiting. FastPanel ships with fail2ban and panel-level rate limiting. Test scripts that hammer the API may get your IP blocked.

Roadmap

• Delete tools (user_delete, site_delete, database_delete, certificate_delete)

• DNS record CRUD

• Backup plan management (list / run / restore)

• Email domain + mailbox management

• Bulk operations (e.g. "apply this nginx hardening to every site")

• CLI-fallback tools over SSH for ops not in REST (transfer, firewall save/restore, panel ip_match)

• Structured MCP outputSchema so clients can render typed results

• Rate-limit aware retry with exponential backoff

Contributing

Issues and PRs welcome. Especially useful:

• Captured DevTools Network payloads for actions not yet covered

• Compatibility fixes for newer FastPanel versions

• Additional DB servers / runtime types in the enum schemas

• Screenshots / recordings of typical flows for the README

License

MIT — see LICENSE.

Disclaimer

This is a third-party, community project. "FastPanel" is a trademark of its respective owners. This project is not affiliated with, endorsed by, or sponsored by FastPanel. Test against a non-production FastPanel instance before pointing it at anything you care about.