Marzban MCP — Claude Code MCP server: what it does, how to install
An MCP server that exposes Marzban panel operations as agent tools, so you can manage accounts from a chat instead of the web UI.
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-mcpWhat Marzban MCP 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.
What it helps with
- 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 for the agent
- 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
How to install Marzban MCP
Platform CLI
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-mcpReplace <…> with your own values
Platform CLI
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-mcpReplace <…> with your own values
Config file
{
"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
Config file
{
"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
Platform CLI
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-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Marzban MCP
How do I install Marzban MCP in Claude Code?
Run `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` and replace the placeholders with your panel URL and admin login.
What does Marzban MCP do?
It registers Marzban panel operations as tools an agent can call, routing them through marzban-sdk for auth and error handling.
Which credentials does it need?
A panel URL plus an admin username and password, passed as MARZBAN_BASE_URL, MARZBAN_USERNAME and MARZBAN_PASSWORD. The server will not connect without all three.
