Overview

marzban-mcp is a Model Context Protocol server built on marzban-sdk. It gives an AI agent — Claude, Cursor, or any other MCP client — a set of tools to manage a Marzban panel: users, subscriptions, nodes, and the core config.

It's a separate package from the SDK itself. If you're building your own integration in code, you want marzban-sdk instead — this section covers the ready-made server for AI clients.

At a glance

• 21 tools, namespaced marzban_<area>_<action>, covering the full user lifecycle plus config, hosts, nodes, system stats, and subscriptions.
• 3 prompts that chain those tools into ready-made investigations (expiring subscriptions, node health, traffic reports).
• Profile-gated access — a tool outside the active profile never appears in tools/list at all, not just hidden behind a hint.
• Every destructive action needs confirmation — a first call only describes the consequences and returns a one-time token; nothing runs until a second, explicitly confirmed call repeats it.
• Credentials only from environment variables — never accepted as a tool argument, so a model can't redirect the server or leak them through a call.
• Credential-bearing fields masked by default — proxies, subscription_url, and links stay hidden unless you opt in.

Quick example

{
  "mcpServers": {
    "marzban": {
      "command": "npx",
      "args": ["-y", "marzban-mcp"],
      "env": {
        "MARZBAN_BASE_URL": "https://panel.example.com",
        "MARZBAN_USERNAME": "admin",
        "MARZBAN_PASSWORD": "secret"
      }
    }
  }
}

Nearly every MCP client reads this same shape — see Client Setup for exact instructions per client. Prefer a container over Node.js on the host? A multi-arch image is published at ilmar7786/marzban-mcp — see Client Setup → Running via Docker.