The Marzban toolkit
for code and AI agents
MarzbanSDK bundles two things: a complete typed TypeScript SDK for building your own Marzban integration — auth, retries, WebSocket streaming, webhooks, runtime validation — and marzban-mcp, an MCP server built on it so an AI agent can run your panel directly. Same auth, same retries, same typed errors, so neither ever drifts from the other.
npm install marzban-sdkMIT licensed · Full official Marzban API coverage · Tree-shakeable ESM + CJS
From install to full API access in minutes
A single function authenticates, configures retries, and exposes every typed API module.
import { createMarzbanSDK, isAuthError } from 'marzban-sdk'
// One call authenticates and wires up every API module.
// Token refresh and retries are handled for you.
const sdk = await createMarzbanSDK({
baseUrl: 'https://panel.example.com',
username: 'admin',
password: 'secret',
})
// Fully typed API surface: users · nodes · system · subscriptions · …
const { users } = await sdk.user.getUsers({ status: 'active', limit: 10 })
const stats = await sdk.system.getSystemStats()
// Stream real-time logs from the core over WebSocket
const close = await sdk.logs.connectByCore({
onMessage: (data) => console.log(data),
})
// Typed, narrowable error handling
try {
await sdk.user.getUserByUsername('does-not-exist')
} catch (err) {
if (isAuthError(err)) await sdk.authorize()
}The whole API, fully typed
Nine ready-to-use modules cover everything Marzban exposes — each with complete TypeScript types and autocomplete.
Users
Create, update, reset and inspect users and their traffic.
Nodes
Manage and monitor connected Marzban nodes.
System
Live stats, host info and core configuration.
Core
Control and restart the Xray core, read its config.
Subscriptions
Resolve subscription links and per-client configs.
User templates
Reusable templates for provisioning users.
Admins
Manage admin accounts and permissions.
Logs
WebSocket log streams from the core and nodes.
Webhooks
Verify and handle inbound Marzban events.
A real SDK, not just a wrapper
MarzbanSDK ships the reliability features every production Marzban integration needs — so you focus on product, not plumbing.
End-to-end type safety
Every endpoint, parameter and response is fully typed. Autocomplete covers the entire Marzban API surface — typed against the official OpenAPI spec.
Isomorphic by design
One package, identical API in Node.js and the browser. Ships dual ESM + CJS builds, is side-effect free, and tree-shakes cleanly.
Flexible auth control
Authenticate automatically on init, pass an existing JWT, or take full manual control. Every mode is fully type-safe.
Auto token refresh
Expired sessions are renewed transparently behind the scenes. Your application code never has to handle a 401.
Built-in retry logic
Configurable exponential back-off for transient network failures and WebSocket reconnects — no boilerplate in your code.
Classified error system
Errors carry structured codes and are narrowed with type guards, so you handle auth, network and validation failures precisely.
Runtime Zod validation
Configuration and payloads are validated at runtime. Misconfigured clients fail fast with clear, actionable messages.
Real-time log streaming
Stream live logs from the Marzban core or any node over WebSocket, with automatic reconnection built in.
Webhooks, batteries included
HMAC-SHA256 signature verification, typed event subscriptions and wildcard handlers for inbound Marzban events.
Structured logging
Environment-aware logger out of the box — verbose in dev, quiet in production — or plug in your own logging stack.
Helpful utilities
First-class helpers for byte conversions, datetime math and subscription template variables — common chores, solved.
Production-hardened
Timeouts, cancellation and defensive defaults are baked in. Built and tested for real workloads, not just demos.
Or hand your panel to an AI agent
Point Claude, Cursor, or any MCP client at your panel with one config block — no custom integration code, built on the same SDK above.
{
"mcpServers": {
"marzban": {
"command": "npx",
"args": ["-y", "marzban-mcp"],
"env": {
"MARZBAN_BASE_URL": "https://panel.example.com",
"MARZBAN_USERNAME": "admin",
"MARZBAN_PASSWORD": "secret"
}
}
}
}Capable, but never unsupervised
Every safety mechanism below is on by default — an agent can only do what its profile allows, and never without your say-so on anything destructive.
Env-only credentials
The panel URL, username and password are never accepted as a tool argument — a compromised or confused model can’t redirect the server elsewhere.
Profile-gated tools
A tool outside the active profile never appears in tools/list at all, not just hidden behind a hint.
Confirmation on destructive actions
The first call only describes the consequences and returns a one-time token; nothing runs until a human-approved second call repeats it.
Credentials masked by default
proxies, subscription_url and links stay hidden unless you explicitly opt in.
21 tools, 3 prompts
Full user lifecycle, config, hosts, nodes, system stats and subscriptions, plus ready-made investigations that chain several tools together.
Built on marzban-sdk
The same typed client, auth and retry behavior as the SDK, just exposed as MCP tools — no drift between them.
Build your Marzban integration the right way
Read the SDK quick-start to build in code, or the MCP server docs to wire it up for an AI agent — either way you’re running the same battle-tested client underneath.