Client Setup

Almost every MCP client reads the same JSON shape — a command/args/env block, keyed by a server name you choose, under an mcpServers object:

{
  "mcpServers": {
    "marzban": {
      "command": "npx",
      "args": ["-y", "marzban-mcp"],
      "env": {
        "MARZBAN_BASE_URL": "https://panel.example.com",
        "MARZBAN_USERNAME": "admin",
        "MARZBAN_PASSWORD": "secret"
      }
    }
  }
}

What differs per client is where that block goes, and occasionally the key it's nested under. Pick your client below.

Running via Docker

Every release is also published as a multi-arch (linux/amd64 + linux/arm64) image at ilmar7786/marzban-mcp. Use this instead of npx when you'd rather not have Node.js on the host, or want a pinned, reproducible runtime.

The server talks MCP over stdio, so the container needs -i (keep stdin open) and --rm (don't leave stopped containers around) — no port to publish, nothing to health-check from outside:

{
  "mcpServers": {
    "marzban": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MARZBAN_BASE_URL",
        "-e", "MARZBAN_USERNAME",
        "-e", "MARZBAN_PASSWORD",
        "ilmar7786/marzban-mcp"
      ],
      "env": {
        "MARZBAN_BASE_URL": "https://panel.example.com",
        "MARZBAN_USERNAME": "admin",
        "MARZBAN_PASSWORD": "secret"
      }
    }
  }
}

-e MARZBAN_BASE_URL with no =value tells Docker to pass that variable through from the process's own environment — which is exactly what the client's env block sets before launching docker run. This is the same pattern for any of the optional configuration variables: add another -e MARZBAN_MCP_... arg and the matching key under env.

Pin a specific version instead of always pulling latest with ilmar7786/marzban-mcp:X.Y.Z — see the tags list or the GitHub Releases for available versions.

Common issues

• First call hangs or times out — npx -y marzban-mcp downloads the package on first run if it isn't cached yet. Give it a minute, especially on a slow connection.
• Nothing shows up after editing the config — every client here needs a restart (or, for VS Code, at least a config reload) to pick up changes. Editing the file alone isn't enough.
• "command not found: npx" — the client launches the server with whatever PATH it sees, which isn't always your shell's PATH (especially for GUI apps on macOS). Make sure Node.js is installed where the client can find it, or use an absolute path to npx in command.