Log inSubmit server
Marzban Sdk logo

Marzban Sdk

by Ilmar7786

Manage Marzban users, subscriptions, nodes, hosts, configuration, and system stats through MCP tools.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Marzban Sdk

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "ilmar7786-marzban-sdk": {
      "command": "npx",
      "args": [
        "-y",
        "marzban-mcp"
      ],
      "env": {
        "MARZBAN_BASE_URL": "YOUR_VALUE_HERE",
        "MARZBAN_USERNAME": "YOUR_VALUE_HERE",
        "MARZBAN_PASSWORD": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

npx -y marzban-mcp

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 3d ago.

Overview

Ilmar7786/marzban-sdk MCP server exposes a Marzban proxy/VPN panel through MCP tools built on the marzban-sdk package. Agents can manage users and subscriptions, inspect nodes and system statistics, and work with hosts and core configuration through an MCP-compatible client. It authenticates with panel credentials supplied as environment variables and supports profiles that control which tools are visible. Reach for it when an agent needs operational access to a Marzban panel with confirmation gates and replay protection for destructive actions.

Use cases

  • Manage Marzban user accounts and renewals
  • Inspect node health and system statistics
  • Audit users with expiring subscriptions
  • Update panel configuration with confirmation
  • Review subscription and traffic information

Key features

  • 21 MCP tools for users, config, nodes, hosts, stats, and subscriptions
  • Three investigation prompts for audits and diagnostics
  • Profile-based tool visibility
  • Confirmation and five-minute replay protection for destructive calls
  • Environment-only panel credentials
  • Credential and subscription-link masking by default

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

4/4 checks healthy over the last 13d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 7d ago via OSV.dev · marzban-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars26Stargazers on the source repository.
npm downloads170Package downloads in the last 30 days.
Last commit8d agoMost recent push to the default branch.
Install checkInconclusiveDidn't respond in our test window — often a slow first install.

How Marzban Sdk works

What Ilmar7786/marzban-sdk MCP server does

Ilmar7786/marzban-sdk MCP server connects MCP-compatible AI clients to a Marzban panel. It exposes 21 namespaced tools covering user management, subscriptions, configuration, hosts, nodes, and system statistics. The package is built on marzban-sdk, using that SDK for authentication, retries, and reconnect behavior.

User operations cover the full lifecycle, including creation and updates, renewals, status changes, and other account actions. Configuration tools provide access to core settings, while system and node tools support operational checks. Subscription tools let an agent work with subscription-related data. Three prompts—expiring_users_audit, node_diagnostics, and traffic_report—combine several tools into predefined investigations.

How it works

An MCP client starts the server with npx -y marzban-mcp and passes the Marzban panel URL and administrator credentials through its MCP configuration. Credentials are kept out of tool arguments. The username and password also support silent re-authentication when the panel session expires.

Profiles determine which tools are exposed to the model. readonly limits access to lists and lookups, standard adds user CRUD, renewals, and status changes, and full adds destructive operations such as deletion, traffic resets, configuration rewrites, and core restarts. A tool outside the selected profile is omitted from tools/list.

Destructive operations use a confirmation flow. The initial request describes the intended effect and returns a one-time token without executing the operation. A second request with that token is required unless confirmation has been disabled. The server also remembers destructive calls for five minutes, returning the recorded result for an identical retry instead of sending the operation to Marzban again. If a request was sent but no response was received, the result is reported as unknown so the state can be checked with a read-only operation.

Setup and configuration

Install the package globally with npm, or let the MCP client run it through npx. A multi-architecture Docker image is also published as ilmar7786/marzban-mcp.

Set these required environment variables in the client’s MCP server entry:

  • MARZBAN_BASE_URL: the Marzban panel URL.
  • MARZBAN_USERNAME: the administrator username.
  • MARZBAN_PASSWORD: the administrator password.

Optional settings control the active profile, response format, verbosity, tool allow/deny filters, logging, link masking, and confirmation behavior. MARZBAN_MCP_CONFIRM accepts auto, always, or off; auto is the default and applies confirmation per tool and exact argument set for five minutes.

Tools and capabilities

  • Manage Marzban users across their lifecycle.
  • Inspect and manage subscriptions.
  • Read and update core configuration, subject to the active profile.
  • Inspect hosts, nodes, and system statistics.
  • Run the expiring_users_audit, node_diagnostics, and traffic_report investigation prompts.
  • Mask proxies, subscription_url, and links by default, with explicit opt-in for their display.

Limitations and notes

The server requires administrator credentials and access to a Marzban panel. Destructive capabilities depend on the full profile and confirmation settings. Setting confirmation to off removes the confirmation safety net and is intended for unattended environments. The in-memory record of destructive calls is cleared when the server restarts.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Marzban Sdk

Ilmar7786/marzban-sdk is an MCP server that connects AI clients to a Marzban proxy/VPN panel through tools for users, subscriptions, configuration, hosts, nodes, and system statistics. It also provides investigation prompts and confirmation controls for destructive operations.

Install it with npm or run it through npx from your MCP client configuration. Use `npx -y marzban-mcp` as the command, or pull the `ilmar7786/marzban-mcp` Docker image for a container-based setup.

Configure `MARZBAN_BASE_URL`, `MARZBAN_USERNAME`, and `MARZBAN_PASSWORD` in the client’s MCP server entry. The client starts `npx -y marzban-mcp` and passes those values as environment variables.

Yes, it works with Cursor through the client’s MCP configuration. Add the server command and the three required Marzban environment variables, then restart Cursor so the tools become available.

It requires a confirmation token before destructive calls execute by default. The first request describes the action, while a second request with the token performs it; identical retries within five minutes return the recorded result instead of repeating the panel operation.

Related MCP servers

All in Cloud Platforms All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewMarzban Sdk AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/ilmar7786-marzban-sdk?style=directory)](https://allmcps.com/mcp/ilmar7786-marzban-sdk)
HTML Embed
<a href="https://allmcps.com/mcp/ilmar7786-marzban-sdk"><img src="https://allmcps.com/api/badge/ilmar7786-marzban-sdk?style=directory" alt="Marzban Sdk on AllMCPs" /></a>