Introduction

MarzbanSDK is a toolkit for building on Marzban: a complete, production-grade TypeScript SDK for your own integrations, and an MCP server built on that same SDK for AI agents. Same auth, same retries, same typed errors underneath either one — pick whichever fits how you're building.

marzban-sdk

A complete, production-grade TypeScript SDK for building Marzban integrations. Beyond fully typed coverage of the entire API, it bundles the infrastructure a real integration needs — authentication with transparent token refresh, retries, WebSocket log streaming, webhook verification, and runtime validation — and behaves identically in Node.js, Bun, Deno, and the browser.

Features

• First-class TypeScript — every request, response, and error is fully typed, generated directly from the Marzban OpenAPI specification. Matching Zod schemas are exported alongside every model.
• Truly cross-runtime — the same API in Node.js, Bun, Deno, and the browser: native WebSocket and the Web Crypto API where available, with a transparent ws fallback for older Node.js.
• Modern build — a dual ESM + CJS bundle, side-effect free and fully tree-shakeable, so you ship only what you use.
• Flexible authentication — log in automatically on startup, pass an existing JWT, or take full manual control; expired sessions refresh transparently on 401, so your code never touches a token.
• Built-in resilience — exponential-backoff retries with a configurable retry count, plus automatic WebSocket reconnects.
• Classified error system — AuthError, HttpError, ConfigurationError, and webhook errors all extend SdkError with a machine-readable code and type-guard helpers.
• Runtime validation — config and all API responses are validated with Zod. Bad data is caught immediately with structured error details.
• Real-time log streaming — sdk.logs streams core and node logs over WebSocket with automatic token refresh and configurable reconnection.
• Webhooks — sdk.webhook handles incoming Marzban events with HMAC-SHA256 signature verification, typed event subscriptions, wildcard listeners, and batch processing.
• Batteries-included utilities — first-class helpers for data-size formatting/parsing, datetime calculations, and template variables.

Module overview

Quick example

import { createMarzbanSDK, formatBytes, humanRemaining } from 'marzban-sdk'

const sdk = await createMarzbanSDK({
  baseUrl: 'https://vpn.example.com',
  username: 'admin',
  password: 'secret',
})

// List active users
const { users, total } = await sdk.user.getUsers({ status: 'active' })
console.log(`${total} active users`)

for (const user of users) {
  const dataLeft = formatBytes((user.data_limit ?? 0) - user.used_traffic)
  const timeLeft = user.expire ? humanRemaining(user.expire * 1000) : '∞'
  console.log(`${user.username} — ${dataLeft} left, expires ${timeLeft}`)
}

marzban-mcp

An MCP server built on marzban-sdk that gives an AI agent — Claude, Cursor, or any other MCP client — a set of tools to manage a Marzban panel directly: users, subscriptions, nodes, and the core config. It's a separate, published package (marzban-mcp), not a mode of the SDK.

• 21 tools, 3 prompts — the full user lifecycle plus config, hosts, nodes, system stats, and subscriptions, and ready-made prompts that chain several tools into one investigation.
• Profile-gated access — a tool outside the active profile never appears in tools/list at all.
• Confirmation on every destructive action — a first call only describes the consequences and returns a one-time token; nothing runs until a second, explicitly confirmed call repeats it.
• Credentials only from environment variables, masked by default in tool output.

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