Configuration
Every marzban-mcp environment variable — what it controls, its default, and the values it accepts.
Configuration is entirely env-based — set these in your MCP client's env block (see Client Setup). Nothing here is ever accepted as a tool argument; see Security for why that's a hard rule, not just a convention.
Credentials
| Variable | Required | Default | Description |
|---|---|---|---|
MARZBAN_BASE_URL | Yes | — | Your panel's URL, e.g. https://panel.example.com |
MARZBAN_USERNAME | Yes | — | Admin username |
MARZBAN_PASSWORD | Yes | — | Admin password |
MARZBAN_TOKEN | No | — | An already-valid session token, to skip the first login call |
MARZBAN_USERNAME/MARZBAN_PASSWORD are required even when MARZBAN_TOKEN is set — see Security for why a token alone isn't enough.
Access control
| Variable | Default | Values | Description |
|---|---|---|---|
MARZBAN_MCP_PROFILE | standard | readonly | standard | full | Which tools get registered at all — see Security |
MARZBAN_MCP_CONFIRM | auto | off | auto | always | How often a destructive tool re-asks for confirmation — see Security |
MARZBAN_MCP_SHOW_LINKS | false | true | false | Whether proxies, subscription_url, and links are shown in full instead of masked |
MARZBAN_MCP_TOOLS_ALLOW | — | Comma-separated globs, e.g. marzban_users_* | If set, only matching tools are registered |
MARZBAN_MCP_TOOLS_DENY | — | Comma-separated globs | Matching tools are never registered — wins over _ALLOW when both match the same tool |
Output shaping
| Variable | Default | Values | Description |
|---|---|---|---|
MARZBAN_MCP_FORMAT | text | text | table | json | How a tool's result is rendered for the model to read |
MARZBAN_MCP_VERBOSITY | compact | compact | full | How many fields each response includes |
MARZBAN_MCP_MAX_CHARS | 8000 | Positive integer | Character budget per response before truncation |
See Response Format & Token Economy for what each of these actually changes.
Logging
| Variable | Default | Values | Description |
|---|---|---|---|
MARZBAN_MCP_LOG_LEVEL | warn | debug | info | warn | error | Minimum level written to stderr |
Logs never go to stdout — stdout is reserved for the JSON-RPC protocol itself, and a single stray byte there would break the connection.
TLS / self-signed certificates
| Variable | Default | Values | Description |
|---|---|---|---|
MARZBAN_TLS_CA_FILE | — | Path to a CA cert (PEM) | Trust this CA in addition to the system store — for a panel behind a self-signed or internal-CA certificate. Relative paths resolve against the process's working directory. |
MARZBAN_TLS_REJECT_UNAUTHORIZED | — | true | false | Escape hatch for a panel you can't get a trusted/known CA for. Setting false disables certificate validation entirely and logs a startup warning — prefer MARZBAN_TLS_CA_FILE whenever the CA is available. |
An unreadable MARZBAN_TLS_CA_FILE fails startup with a ConfigError naming the resolved path, rather than a bare ENOENT.