# Marzban MCP

An MCP server that exposes Marzban panel operations as agent tools, so you can manage accounts from a chat instead of the web UI.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 26
- Author: Ilmar7786
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Ilmar7786/marzban-sdk
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/mcp/marzban-mcp

## What it does

The server is a thin client over `marzban-sdk`, a TypeScript toolkit for the Marzban API. Auth, retries and typed errors come from the SDK itself. That matters because the server and any code you write on the same library talk to the panel the same way, and the command-line tool in the repository shares that client too.

It ships as the npm package `marzban-mcp` and runs through `npx`; there is also a Docker image, `ilmar7786/marzban-mcp`. Three environment variables are required before it starts: `MARZBAN_BASE_URL`, `MARZBAN_USERNAME` and `MARZBAN_PASSWORD`. Without a real panel address and admin credentials the connection never opens, so gather those first. Panel credentials then sit in your MCP configuration file, and who can read that file is worth a look.

What the agent can actually reach depends on the tools the server registers and on how precisely you word the request.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `MARZBAN_BASE_URL`, `MARZBAN_USERNAME`, `MARZBAN_PASSWORD` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add marzban-mcp -e MARZBAN_BASE_URL=<MARZBAN_BASE_URL> -e MARZBAN_USERNAME=<MARZBAN_USERNAME> -e MARZBAN_PASSWORD=<MARZBAN_PASSWORD> -- npx -y marzban-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add marzban-mcp --env MARZBAN_BASE_URL=<MARZBAN_BASE_URL> --env MARZBAN_USERNAME=<MARZBAN_USERNAME> --env MARZBAN_PASSWORD=<MARZBAN_PASSWORD> -- npx -y marzban-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "marzban-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "marzban-mcp"
            ],
            "env": {
                "MARZBAN_BASE_URL": "<MARZBAN_BASE_URL>",
                "MARZBAN_USERNAME": "<MARZBAN_USERNAME>",
                "MARZBAN_PASSWORD": "<MARZBAN_PASSWORD>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "marzban-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "marzban-mcp"
            ],
            "env": {
                "MARZBAN_BASE_URL": "<MARZBAN_BASE_URL>",
                "MARZBAN_USERNAME": "<MARZBAN_USERNAME>",
                "MARZBAN_PASSWORD": "<MARZBAN_PASSWORD>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e MARZBAN_BASE_URL=<MARZBAN_BASE_URL> -e MARZBAN_USERNAME=<MARZBAN_USERNAME> -e MARZBAN_PASSWORD=<MARZBAN_PASSWORD> marzban-mcp npx -y marzban-mcp
```
Replace <…> with your own values

## When to use it
- read panel state from a chat with an agent
- add a Marzban user without opening the web panel
- list accounts and their traffic limits
- edit an existing account from a written description
- keep agent actions and SDK code on the same client

## Example prompts
- List the users in my Marzban panel with their current status
- Create a Marzban user matching the limits I describe
- Find the accounts that have already expired and show their settings

## Similar
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [Oh My Posh Validator](https://affpapa.org/en/nevibecode/mcp/oh-my-posh-validator.md) — MCP server · ★ 23643
- [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18727
- [Coder](https://affpapa.org/en/nevibecode/mcp/coder.md) — MCP server · ★ 17160
- [mcp](https://affpapa.org/en/nevibecode/mcp/kubeshark-mcp.md) — MCP server · ★ 12109

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md