# Docs

- [Introduction](/docs): The Marzban toolkit — marzban-sdk, a complete typed TypeScript client, and marzban-mcp, an MCP server built on it for AI agents. Node.js, Bun, Deno, and the browser.
- Get Started
  - [Installation](/docs/get-started/installation): Install MarzbanSDK with npm, yarn, pnpm, bun, Deno, or a CDN, and run it in Node.js, Bun, Deno, the browser, and edge runtimes.
  - [Quick Start](/docs/get-started/quick-start): Create a client and make your first authenticated request in under a minute.
  - [TypeScript & Modules](/docs/get-started/typescript): First-class types, ESM and CJS support, and how to use SDK types in your own code.
- Configuration
  - [Config Options](/docs/configuration/config-options): Every MarzbanSDK configuration field — `baseUrl`, auth, `timeout`, `retries`, logger and webhook secret — with defaults and Zod validation rules.
  - [Logging](/docs/configuration/logging): Environment-aware built-in logging and how to plug in your own logger.
- Authentication
  - [Auto Authentication](/docs/authentication/auto-authentication): How the SDK authenticates on init and transparently refreshes tokens on 401.
  - [Manual Auth & Tokens](/docs/authentication/manual-auth): Disable auto-auth, call authorize() manually, or supply an existing JWT token.
- Modules
  - [Users](/docs/modules/users): Create, list, update, reset, enable, disable, and delete Marzban users — manage data limits, expiry, status, and traffic, fully typed via `sdk.user`.
  - [Admins](/docs/modules/admins): Create, update, query, and delete Marzban administrators — manage sudo privileges, Telegram and Discord links, and per-admin usage via `sdk.admin`.
  - [Nodes](/docs/modules/nodes): Add, query, update, and monitor Marzban worker nodes — addresses, ports, status, and reconnection — with full type safety via `sdk.node`.
  - [System](/docs/modules/system): Server stats, inbound listing, and proxy host management via sdk.system.
  - [Core](/docs/modules/core): Read Xray core stats, inspect and update the JSON config, and restart the engine through `sdk.core` — fully typed against the Marzban API.
  - [Subscriptions](/docs/modules/subscriptions): Subscription endpoints for fetching user configs and usage via sdk.subscription.
  - [User Templates](/docs/modules/user-templates): Create and manage reusable user configuration templates via sdk.userTemplate.
- Real-time
  - [WebSocket Logs](/docs/realtime/websocket-logs): Stream live logs from the Marzban Xray core and individual nodes over WebSocket, with automatic token refresh and reconnection via `sdk.logs`.
- Webhooks
  - [Event Types](/docs/webhooks/event-types): The 12 webhook actions Marzban emits, their payloads, and how to consume them type-safely.
  - [Signature Verification](/docs/webhooks/signature-verification): Verify Marzban webhook signatures with HMAC-SHA256 using the Web Crypto API — server-side only, with the x-signature header and your shared secret.
  - [Express](/docs/webhooks/express): Handling Marzban webhooks in Express — raw body middleware and signature verification.
  - [Fastify](/docs/webhooks/fastify): Handling Marzban webhooks in Fastify — raw body access and signature verification.
  - [NestJS](/docs/webhooks/nestjs): Handling Marzban webhooks in NestJS with RawBodyRequest and signature verification.
  - [Next.js](/docs/webhooks/nextjs): Receive and verify Marzban webhooks in Next.js App Router Route Handlers — read the raw request body and validate the HMAC-SHA256 signature.
  - [Hono / Edge](/docs/webhooks/hono-edge): Handling Marzban webhooks on Hono and edge runtimes (Cloudflare Workers, Vercel Edge).
- Integrations
  - [Node.js / Bun / Deno](/docs/integrations/node-bun-deno): Use MarzbanSDK in plain server runtimes — Node.js 18+, Bun 1.0+, and Deno 1.38+ — with no framework and zero extra configuration.
  - [React](/docs/integrations/react): Initializing and using MarzbanSDK in React apps with hooks and TanStack Query.
  - [Vue](/docs/integrations/vue): Initialize MarzbanSDK in Vue 3 with a provide/inject composable, and learn when client-side usage is safe versus proxying through a backend.
  - [Next.js](/docs/integrations/nextjs): Using MarzbanSDK in Next.js App Router — Server Components, Route Handlers, and Server Actions.
  - [NestJS](/docs/integrations/nestjs): Integrate MarzbanSDK into NestJS by wrapping the client in a global module that initializes it on onModuleInit and exposes it as an injectable service.
- Advanced
  - [Error Handling](/docs/advanced/error-handling): Handle failures with MarzbanSDK's typed error hierarchy — every error extends `SdkError` with a machine-readable `code` and a matching type guard.
  - [Data Validation](/docs/advanced/validation): Runtime validation with Zod — config schemas, API response schemas, and webhook payloads.
  - [HTTP & Retry](/docs/advanced/http-retry): Timeouts, automatic retries with exponential backoff, and network resilience.
- Utilities
  - [Data Sizes](/docs/utilities/data-sizes): Parse, format, and convert data sizes — turn Marzban's raw byte values into human-readable strings and back.
  - [Datetime](/docs/utilities/datetime): Helpers for working with dates, expiry times, and human-readable durations.
  - [Template Variables](/docs/utilities/template-variables): Work with Marzban host-settings template variables — extract, validate, and interpolate.
  - [Pagination](/docs/utilities/pagination): Walk every page of a paginated endpoint without hand-writing the offset/limit loop yourself.
- MCP Server
  - [Overview](/docs/mcp-server/overview): marzban-mcp — an MCP server that lets AI agents manage a Marzban panel through marzban-sdk, with profile-gated tools and confirmation on every destructive action.
  - [Client Setup](/docs/mcp-server/client-setup): How to connect marzban-mcp to Claude Desktop, Claude Code, Cursor, Cline, Windsurf, Continue.dev, and VS Code Copilot.
  - [Configuration](/docs/mcp-server/configuration): Every marzban-mcp environment variable — what it controls, its default, and the values it accepts.
  - [Response Format & Token Economy](/docs/mcp-server/response-format): How marzban-mcp shapes tool output — format, verbosity, pagination, and truncation — to keep responses cheap without hiding anything.
  - [Security](/docs/mcp-server/security): How marzban-mcp handles credentials, gates access by profile, and confirms every destructive action before it runs — in full detail.
  - [Tools](/docs/mcp-server/tools): All 21 marzban-mcp tools, grouped by area, with their scope and what each one does.
  - [Prompts](/docs/mcp-server/prompts): The 3 built-in MCP prompts — ready-made investigations that chain marzban-mcp's tools together.
- AI Tools
  - [Context7](/docs/ai-tools/context7): How AI coding assistants can pull current marzban-sdk and marzban-mcp documentation on demand, instead of answering from stale training data.
- Resources
  - [Contributing](/docs/resources/contributing): How to contribute to MarzbanSDK — reporting bugs, submitting PRs, and development setup.
  - [Changelog](/docs/resources/changelog): MarzbanSDK release history, version compatibility, breaking changes, and migration notes — including the v3.0.0 async webhook and Web Crypto updates.
  - [FAQ](/docs/resources/faq): Answers to common MarzbanSDK questions — Marzban version support, browser and runtime compatibility, authentication, token refresh, and webhooks.