Marzban MCP server

Read from the package source without running it. The installed server may list more.

• marzban_config_get

  Reads the Xray core configuration. Defaults to a structural summary (inbound/outbound tags, ports, protocols, routing rule count) \u2014 the full config can be tens of KB and this is usually all that's needed. Pass `section` (e.g. "inbounds") for one key's raw JSON, or `section: "raw"` for the entire config.

• marzban_config_updatewrite action

  Overwrites the entire Xray core configuration and restarts the core \u2014 this is the single most disruptive operation on the whole panel, dropping every active connection while it restarts. Replaces the config wholesale, not a patch. Set `dryRun: true` first to preview the diff against the current config without writing or restarting anything (no confirmation needed for a dry run). Requires conf

• marzban_core_restart

  Restarts the Xray core and every connected node, dropping all active connections. Use marzban_config_update instead if the goal is to apply a config change \u2014 it restarts the core as part of applying, so a separate restart is rarely needed. Requires confirmation.

• marzban_hosts_get

  Lists proxy host settings grouped by inbound tag. Flags host fields (remark/address/host/sni/path) that reference an unknown `{VARIABLE}` template token \u2014 almost always a typo, since Marzban leaves unknown tokens un-substituted rather than erroring.

• marzban_hosts_updatewrite action

  Overwrites the entire proxy host configuration (all inbound tags at once) \u2014 this replaces the whole map, not a per-tag patch, so include every tag you want to keep. May change subscription links/configs for affected users. Requires confirmation.

• marzban_nodes_list

  Lists all connected nodes with their status and Xray version, plus bandwidth usage (uplink/downlink) over the given period. `start`/`end` (ISO datetimes) narrow the usage window; omit both for all-time.

• marzban_subscription_info

  Reads subscription status/usage/expiry using the token from a subscription URL (the same public, unauthenticated endpoint client apps use) \u2014 for diagnosing a broken subscription link without needing the username. For an admin-side lookup by username, use marzban_users_get instead.

• marzban_system_inbounds

  Lists configured inbound proxies grouped by protocol, with tag, network, TLS mode, and port for each. For the raw Xray inbound JSON (routing, stream settings, etc.) use marzban_config_get with section: "inbounds" instead.

• marzban_system_stats

  Reports panel-wide stats: CPU/memory usage, user counts by status, and bandwidth totals/speeds, plus the Xray core version and whether it is currently running.

• marzban_users_activate

  Sets a user's status to active.

• marzban_users_createwrite action

  Creates a new user. `dataLimit` accepts a human size ("10GB"), `expire` a relative duration ("30d") or absolute date \u2014 both default to unlimited when omitted. `templateId` fills dataLimit/inbounds/expire from a user template; any field also given explicitly overrides the template value.

• marzban_users_deactivate

  Sets a user's status to disabled, immediately blocking their access without deleting them.

• marzban_users_deletewrite action

  Permanently deletes a user, along with their subscription link and traffic history. Irreversible \u2014 requires confirmation. Prefer marzban_users_deactivate if you only need to block access without losing their data.

• marzban_users_extend

  Renews a user: adds addDuration to their current expiration (or to now, if they have none or it already passed) and/or addData on top of their current data limit. If the user was expired or limited, status is moved back to active. Use this instead of marzban_users_update for renewals \u2014 it reads the current expire/limit first so the increment is relative, not an absolute overwrite.

• marzban_users_get

  Fetches one user by username, with a computed summary: data left, days left, usage percent, and whether they are effectively expired (covers the case where status has not caught up with an already-past expire yet).

• marzban_users_hold

  Sets a user's status to on_hold \u2014 inactive until their first connection, at which point the on-hold timer starts. Useful for provisioning an account ahead of time without starting its clock.

• marzban_users_list

  Lists users, optionally filtered by status or a search term (matches username/note). Paginated \u2014 default 25, max 100 per call; prefer `search` over paging through everyone. For one known username, use marzban_users_get instead.

• marzban_users_reset_traffic

  Resets used traffic back to zero for one user, or for every user at once when `all: true`. Does not change data_limit or expire. Irreversible \u2014 requires confirmation; `all: true` affects every user on the panel in one call.

• marzban_users_revoke_subscription

  Issues a new subscription link for a user and invalidates the old one. Use when a link has leaked or needs rotating \u2014 not for routine renewals (use marzban_users_extend for those). Requires confirmation.

• marzban_users_updatewrite action

  Partially updates a user \u2014 only fields you provide are changed, everything else is left as-is. For status changes prefer marzban_users_activate/deactivate/hold (clearer intent, no need to know the raw status enum). For renewing an expiring/expired user prefer marzban_users_extend.

• marzban_users_usage

  Reports how much data a user has used: total, lifetime total, their current limit, and a breakdown by node. `start`/`end` (ISO datetimes) narrow the per-node breakdown to a period; omit both for all-time.

• Code scan2 source files scanned25/25
• –Live reliabilityno gateway calls yet and no remote to proben/a
• –Tool poisoningtools not inspected (local package is not executed); not countedn/a
• Auth qualitystatic API keys via environment variables6/15
• Maintenancelast push 9 days ago15/15
• Maintainer identityregistry namespace matches repository owner; GitHub account older than a year8/10

Marzban MCP: common questions

Is Marzban MCP server safe?

Mostly: it is graded B (83/100). Read the Marzban MCP safety report

How do I install Marzban MCP?

It runs on your machine. Copy the Claude Code, Claude Desktop or Cursor config from the install section.

Does Marzban MCP need an API key?

Yes. The registry entry asks for MARZBAN_PASSWORD.

Is Marzban MCP maintained?

The last commit was 10 days ago (2026-09-11). The latest release is v0.3.0.