# 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.

Source: https://featherpanel.com/docs/panel/mcp-server/

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](https://featherpanel.com/docs/user/account#mcp).

## How it runs

The [Docker Compose install](https://featherpanel.com/docs/panel/installation/docker) 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](https://featherpanel.com/docs/panel/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:

```json
{
  "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](https://featherpanel.com/docs/api/authentication).

## Local stdio mode

```bash
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.