marzban-mcp

marzban-mcp

An MCP server that lets AI agents manage a Marzban panel — built on marzban-sdk.

Users, subscriptions, nodes, and the core config — through Claude, Cursor, or any MCP-compatible client.

Documentation · Client Setup · Tools

Point an AI agent at your panel and it can actually run it — not just read about it. No custom integration code, just an entry in your MCP config.

Install

npm install -g marzban-mcp

You don't usually need to install it yourself — your MCP client runs it via npx (see below). Prefer a container? A multi-arch image is published at ilmar7786/marzban-mcp:

docker pull ilmar7786/marzban-mcp

Quick start

Add it to your client's MCP config with your panel's URL and an admin login. Every client reads roughly the same shape:

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

Claude Desktop, Claude Code, Cursor and other MCP clients all read the same mcpServers block — just from a different config file. Restart the client and the tools below become available.

Features

• 🔒 Env-only credentials — the panel URL, username and password are never accepted as a tool argument, so a compromised or confused model can't redirect the server elsewhere.
• 🎯 Profile-gated tools — a tool outside the active profile never appears in tools/list at all, not just hidden behind a hint.
• ✅ Confirmation on every destructive call — the first call only describes the consequences and returns a one-time token; nothing runs until a human-approved second call repeats it, and confirming one call never authorizes a different target or a wider version of the same call.
• 🔁 A retried destructive call doesn't run twice — an identical repeat within 5 minutes returns the recorded result of the first one instead of restarting the core again; a call whose outcome was never observed says so plainly rather than guessing.
• 🙈 Credentials masked by default — proxies, subscription_url and links stay hidden unless you explicitly opt in.
• 🧭 21 tools, 3 prompts — full user lifecycle, config, hosts, nodes, system stats and subscriptions, plus ready-made investigations that chain several tools together.
• 🛠️ Built on marzban-sdk — the same auth, retry and reconnect behavior as the SDK itself, just exposed as MCP tools.

Configuration

Variable	Required	Description
MARZBAN_BASE_URL	Yes	Your panel's URL, e.g. https://panel.example.com
MARZBAN_USERNAME	Yes	Admin username
MARZBAN_PASSWORD	Yes	Admin password — also used to silently re-authenticate on expiry

Everything else — profile, output format, verbosity, tool allow/deny filters, log level, link masking — is optional and documented in Configuration.

Tools

21 tools, namespaced marzban_<area>_<action>: Users (11) · Config (5) · System & nodes (3) · Subscription (2). Three prompts — expiring_users_audit, node_diagnostics, traffic_report — chain those tools into ready-made investigations. Full list at Tools & Prompts.

Safety model

A profile isn't a hint — a tool outside it never appears in tools/list, so a model can't call what it can't see. readonly exposes only lists and lookups; standard (default) adds full user CRUD, renewals and status changes; full adds destructive tools — delete, reset traffic, rewrite config, restart the core.

Destructive tools also gate on confirmation: the first call never runs anything — it describes exactly what would happen and returns a one-time token. Only a second call, with that token attached, executes. MARZBAN_MCP_CONFIRM controls how often this is required: auto (default, once per tool and exact arguments, for 5 minutes — a different target or a wider call always needs its own confirmation), always (every call), or off (unattended environments only — no safety net once set).

Confirmation decides whether a call may run; it doesn't decide whether it has already run. So each destructive call is also remembered for 5 minutes: an identical repeat — the kind a client sends after a timeout — returns the recorded result of the first one, with a note saying so, and never reaches the panel. When a request went out and no answer came back, the outcome is reported as unknown, with instructions to check the state with a read-only tool rather than retry. A fresh confirmation still runs the operation for real, and restarting the server clears the memory.

Documentation

Full setup guides and the complete tool/prompt reference live at ilmar7786.github.io/marzban-sdk:

• Client setup & Configuration
• Tools & Prompts
• Response format
• Security

Contributing

This package lives in the marzban-sdk monorepo — see the root CONTRIBUTING.md for how to submit a patch. Running the server locally in watch mode, poking it with the MCP Inspector, or wiring a client to your own build? See ARCHITECTURE.md § Local development & manual testing. Found a bug or have an idea? Open an issue.

License

MIT © ilmar7786

_{If marzban-mcp saves you time, consider giving it a ⭐ on GitHub.}