mcpField
M
Marzban MCP

Marzban MCP

Local
github.com/Ilmar7786Cloud & Infra26Updated 1w ago
Repository

About Marzban MCP

Marzban MCP is a TypeScript-based MCP server for managing Marzban panels, aimed at AI agents and MCP clients. It shares the MarzbanSDK with related tools, keeping authentication and API behavior consistent.

Key features

  1. 01Manage Marzban panel operations
  2. 02Built on the Marzban TypeScript SDK
  3. 03Shared authentication and retry behavior

Use cases

  1. 01Manage a Marzban panel from an AI agent
  2. 02Use Marzban operations through an MCP client

MCP support

It exposes Marzban operations as tools for AI agents and other MCP clients.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "ilmar7786-marzban": {
      "command": "npx",
      "args": [
        "-y",
        "marzban-mcp"
      ],
      "env": {
        "MARZBAN_BASE_URL": "<MARZBAN_BASE_URL>",
        "MARZBAN_USERNAME": "<MARZBAN_USERNAME>",
        "MARZBAN_PASSWORD": "<MARZBAN_PASSWORD>"
      }
    }
  }
}
Run commandnpx -y marzban-mcp
Environment variables to set
MARZBAN_BASE_URLURL of the Marzban panel.
MARZBAN_USERNAMEMarzban administrator username.
MARZBAN_PASSWORDSecretMarzban administrator password.

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npmmarzban-mcp0.4.0
ocidocker.io/ilmar7786/marzban-mcp:0.4.0

Tools

15

Saved tool list · updated 1w ago

ParameterTypeRequiredDescription
sectionstringNoReturn this one top-level key's raw JSON instead of the summary (e.g. "inbounds", "routing"). Use "raw" for the entire config. Omit for a structural summary — prefer that over "raw" unless you specifically need the full JSON.

Details

From the project README
MarzbanSDK

MarzbanSDK

A TypeScript toolkit for the Marzban API.

CI license

Documentation · SDK · MCP Server

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

PackagenpmDockerWhat it is
packages/sdkmarzban-sdk—The TypeScript SDK — auth, retries, resilient WebSocket reconnects, webhooks, lifecycle
packages/mcpmarzban-mcpilmar7786/marzban-mcpAn 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

If this project saves you time, consider giving it a ⭐ on GitHub.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.