# Ilmar7786/marzban-sdk [Health: Active]

**Category:** ☁️ Cloud Platforms  
**Repository:** https://github.com/Ilmar7786/marzban-sdk/tree/main/packages/mcp  
**GitHub Stars:** 26  
**npm Downloads (last month):** 170  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ilmar7786-marzban-sdk

## Description
/🏠 - Manage the Marzban proxy/VPN panel: users, subscriptions, nodes, hosts, config and system stats, with confirmation for destructive calls.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "marzban-sdk": {
    "command": "npx",
    "args": ["-y","marzban-mcp"],
    "env": {
      "MARZBAN_BASE_URL": "",
      "MARZBAN_USERNAME": "",
      "MARZBAN_PASSWORD": ""
    }
  }
}
```

**Requires environment variables:** `MARZBAN_BASE_URL`, `MARZBAN_USERNAME`, `MARZBAN_PASSWORD` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/ilmar7786-marzban-sdk/readme_