easypanel-mcp

MCP server for EasyPanel — manage your server, projects, services, databases, and domains through any MCP-compatible AI agent (Claude, Cursor, etc.).

42 curated tools + raw tRPC access to all 347 EasyPanel API procedures.

🚀 Quick Setup (Deploy on EasyPanel)

The easiest way — deploy the MCP server as a service on your own EasyPanel. Pick an auth mode:

• OAuth (recommended) — users sign in with their Easypanel email/password in a browser popup. No tokens to generate or paste. Per-user access.
• Bearer — one shared API key + one Easypanel token baked into env vars. MCP_API_KEY is required: the server refuses to start without it.

OAuth mode (browser sign-in, per-user)

1. Create a project (e.g. mcp), add an App service from GitHub dray-supadev/easypanel-mcp
2. Add a domain (e.g. mcp.your-domain.com)
3. Set environment variables:

   EASYPANEL_URL=http://easypanel:3000
   EASYPANEL_MCP_MODE=http
   EASYPANEL_AUTH_MODE=oauth
   OAUTH_ISSUER_URL=https://mcp.your-domain.com
   MCP_ACCESS_MODE=readonly
   PORT=3000
   

   EASYPANEL_AUTH_MODE=oauth is what makes MCP_API_KEY unnecessary here. In the default bearer mode an HTTP deployment requires MCP_API_KEY and the server refuses to start without it.

4. (Optional but recommended) Mount a volume at /data and set OAUTH_STORE_PATH=/data/oauth.json so tokens survive redeploys.
5. Deploy.

Connect Claude Desktop or another OAuth-aware MCP client:

{
  "mcpServers": {
    "easypanel": { "url": "https://mcp.your-domain.com/mcp" }
  }
}

On first use the client will pop a browser window asking for your Easypanel credentials, then return you to Claude with an access token. No manual curl required.

The login page calls Easypanel’s auth.login internally and binds the session token to an opaque OAuth access token scoped to this MCP server. Credentials are never stored.

Bearer mode (shared key, simpler)

1. Get your API token:

   curl -X POST https://YOUR_PANEL:3000/api/trpc/auth.login \
     -H "Content-Type: application/json" \
     -d '{"json":{"email":"[email protected]","password":"your-pass"}}'
   

   If you have 2FA enabled, add "code":"123456" with your authenticator code.

   The response contains "token":"xxx" — that’s your API token.

   ⚠️ This is a session token that expires in 30 days. For a permanent token, use users.generateApiToken (see below).

2. Deploy on EasyPanel:

   EASYPANEL_URL=http://easypanel:3000
   EASYPANEL_TOKEN=your-api-token
   EASYPANEL_MCP_MODE=http
   MCP_API_KEY=your-secret-key
   MCP_ACCESS_MODE=readonly
   PORT=3000
   

   Important: Use http://easypanel:3000 (internal Docker network) when deploying on the same EasyPanel instance.