MCP Server

Active

MIT

Marzban MCP MCP Server

io.github.Ilmar7786/marzban-mcp

Manage Marzban VPN panels through Claude and Cursor with AI agents.

What is the Marzban MCP MCP server?

The Marzban MCP server is a TypeScript toolkit that exposes Marzban panel operations as tools for AI agents like Claude and Cursor. It provides authenticated, resilient access to Marzban APIs through the Model Context Protocol, enabling AI-driven panel management and automation.

Marzban MCP bridges your Marzban VPN panel and AI agents, letting Claude or Cursor manage users, subscriptions, and panel operations via natural language. Built on a shared TypeScript SDK, it maintains consistency across CLI, MCP server, and custom applications while handling authentication, retries, and WebSocket reconnects automatically.

How to install Marzban MCP

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

Environment / auth

MARZBAN_BASE_URL
required
URL of the Marzban panel.
MARZBAN_USERNAME
required
Marzban administrator username.
MARZBAN_PASSWORD
required
secret
Marzban administrator password.

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "marzban-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "marzban-mcp"
      ],
      "env": {
        "MARZBAN_BASE_URL": "<YOUR_MARZBAN_BASE_URL>",
        "MARZBAN_USERNAME": "<YOUR_MARZBAN_USERNAME>",
        "MARZBAN_PASSWORD": "<YOUR_MARZBAN_PASSWORD>"
      }
    }
  }
}

Use cases

Manage Marzban user accounts and subscriptions through conversational AI
Automate VPN panel operations without writing custom scripts
Query panel status and user metrics using natural language
Integrate Marzban management into AI-powered workflows in Claude or Cursor
Monitor and adjust panel configuration via AI agents

Marzban MCP MCP server FAQ

What is Marzban MCP?

Marzban MCP is an MCP server that exposes Marzban VPN panel operations as tools for AI agents. It lets Claude, Cursor, and other MCP clients manage users, subscriptions, and panel settings through natural language commands.

Is Marzban MCP free?

Yes, Marzban MCP is open-source under the MIT license.

How do I install it in Cursor or Claude?

Install via npm (`npm install marzban-mcp`) or use the Docker image (`docker.io/ilmar7786/marzban-mcp:0.3.0`). Configure it in your MCP client settings with your Marzban panel URL and authentication credentials.

What authentication does it require?

You need credentials for your Marzban panel — the MCP server handles authentication, retries, and secure WebSocket connections to your panel automatically.

Can I use this with my own applications?

Yes. The underlying `marzban-sdk` TypeScript package can be used directly in Node, Bun, Deno, or browser applications for custom integrations.

What Marzban operations does it support?

The MCP server exposes Marzban API operations through the shared SDK. See the full documentation at ilmar7786.github.io/marzban-sdk for the complete typed API reference.

README (reference)

Source of truth, from the repository.

MarzbanSDK

A TypeScript toolkit for the Marzban API.

Documentation · SDK · MCP Server

</div>

One TypeScript SDK for Marzban, and everything built on top of it. Fix a bug or add an endpoint in the SDK, and the MCP server, the CLI, and every app built on it get it for free.

How it fits together

flowchart LR
    Panel(["Marzban Panel"])
    SDK["marzban-sdk"]
    MCP["marzban-mcp<br/>MCP server"]
    CLI["marzban-cli<br/>CLI · WIP"]
    App["Your app<br/>Node · Bun · Deno · Browser"]
    Agents(["Claude · Cursor · any MCP client"])

    Panel <--> SDK
    SDK --> MCP --> Agents
    SDK --> CLI
    SDK --> App

The SDK talks to your Marzban panel. The MCP server and CLI are just clients of that same SDK — same auth, same retries, same typed errors — so they never drift from each other or from your own code.

Packages

Package	npm	Docker	What it is
`packages/sdk`	`marzban-sdk`	—	The TypeScript SDK — auth, retries, resilient WebSocket reconnects, webhooks, lifecycle
`packages/mcp`	`marzban-mcp`	`ilmar7786/marzban-mcp`	An MCP server exposing Marzban operations as tools for AI agents
`packages/cli`	—	—	A CLI on top of the SDK — WIP, unpublished
`apps/docs`	—	—	The documentation site

Each publishable package has its own version, README.md, changelog and release tags (sdk-v*, mcp-v*, cli-v*).

Documentation

Full guides, configuration reference and the complete typed API live at ilmar7786.github.io/marzban-sdk.

For how the repository itself is built — architecture, conventions, testing, CI and releases — see docs/.

Contributing

Contributions are welcome — see CONTRIBUTING.md for how to submit a patch. Found a bug or have an idea? Open an issue.

License

MIT © ilmar7786

<div align="center"> <sub>If this project saves you time, consider giving it a ⭐ on <a href="https://github.com/Ilmar7786/marzban-sdk">GitHub</a>.</sub> </div>

Related MCP servers

Vältgeist Domains

Daily GoDaddy auction data: is a domain at auction, its appraisal, price and bid count.

View repository →

Krauncher analyzer

Active

How long a GPU job will run and cost, before running it — static code analysis, never executed.

Python

MIT

View repository →

WEEEK (smart)

Active

WEEEK tasks by name, not IDs — an MCP server

TypeScript

MIT

View repository →

hypruse

Active

Computer use for Hyprland: semantic desktop state over IPC, plus vision and native input

Python

MIT

View repository →

Bollard MCP

An AI-powered, safe database access gateway built on the Model Context Protocol (MCP).

io.github.ImJaineel/SN-MCP-Server

Active

Multi-instance read-only MCP server for ServiceNow

JavaScript

View repository →