MCP server

Connect AI clients to FeatherPanel through the bundled MCP server: OAuth for Claude, API keys for Cursor, local stdio mode, environment variables and tools.

On this page

The MCP server lets AI clients that speak the Model Context Protocol, such as Claude and Cursor, manage a user’s services through the panel API. Users find their endpoint and ready-made config under Account, MCP.

How it runs

The Docker Compose install includes an mcp service (ghcr.io/mythicalltd/featherpanel-mcp) listening on port 3001 inside the Docker network. The frontend container proxies these paths to it:

/mcp, the MCP endpoint, so the public URL is https://<panel>/mcp;
the OAuth paths /.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server, /authorize, /token, /register, /revoke and /oauth.

Nothing extra is needed in your web server config if it already forwards everything to the frontend.

Authentication

Client	How
Claude custom connector	Add `https://<panel>/mcp`, click Connect, sign in to the panel and approve. The approval creates an API key, or you paste an existing one. OAuth uses dynamic client registration and PKCE.
Cursor and clients with static headers	`Authorization: Bearer <api key>` or an `x-api-key` header.
Local stdio	`FEATHERPANEL_URL` and `FEATHERPANEL_API_KEY` environment variables.

Example remote config:

{
  "mcpServers": {
    "featherpanel": {
      "url": "https://panel.example.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Create keys under Account, API Keys and limit them to known IPs where you can. See API authentication.

Local stdio mode

cd mcp
pnpm install && pnpm build
export FEATHERPANEL_URL=https://panel.example.com
export FEATHERPANEL_API_KEY=YOUR_API_KEY
pnpm start:stdio

Environment variables

Variable	Compose value	Notes
`FEATHERPANEL_URL`	`http://backend:80`	Panel API the server calls.
`FEATHERPANEL_API_KEY`	not set	Required in stdio mode.
`MCP_HOST`, `MCP_PORT`	`0.0.0.0`, `3001`	Listen address.
`MCP_PUBLIC_URL`	not set	Public origin for OAuth redirects. Taken from the request Host when empty.
`MCP_OAUTH_STORE_PATH`	`/data/oauth-store.json`	OAuth clients and tokens, kept in the `mcp_oauth_data` volume.
`MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL`	`true`	Allows an `http://` issuer for panels without HTTPS.

Tools

The server reads the public panel settings and only lists tools for enabled modules.

Pack	Enabled by	Examples
Account	always	Who am I, notifications, SSH keys, sessions
Game servers	`module_game_enabled`	Power, console commands and logs, files, startup, reinstall, allocations, firewall, proxies, subdomains, backups, databases, schedules, subusers
Web hosting	`module_web_enabled`	WebSpace files, databases, mail, DNS, SSL, backups, schedules, SFTP, apps and Git deploy
VDS	`module_vds_enabled`	Power, hardware, networking, ISO fetch, reinstall, VNC ticket, backups, subusers
Tickets	`ticket_system_enabled`	List, create, reply, close
Knowledge base	`knowledgebase_enabled`	Search and read articles

Plugins, FeatherOS, the in-panel chatbots and multipart uploads are not exposed. Destructive tools such as kill, wipe, reinstall and delete work whenever the key’s user has that permission, so treat keys like passwords.

Frequently asked questions

Can the MCP server do more than my account can?

No. It calls the panel API with your API key or OAuth grant, so every tool is limited to what that user, and their subuser permissions, allow.

Is the MCP server part of the all-in-one image?

No. It ships as its own featherpanel-mcp container in the Docker Compose install. You can also run it locally in stdio mode.

How do I turn tools off?

Tool packs follow the panel modules. Disabling game servers, web hosting, VDS, tickets or the knowledge base also removes their tools.