Skip to main content
Glama

3xui-mcp

MCP (Model Context Protocol) server for the 3x-ui panel, built on 3xui-api-client. Manage inbounds and clients on your VPN panel directly from Claude, Cursor, VS Code, or any MCP-compatible client.

Scoped intentionally to keep tool context small: read operations plus full CRUD for inbounds and clients. Nodes, groups, geo files, backups, Xray config, and panel settings are out of scope — see Contributing if you need them.

Contents

Related MCP server: Clash Control MCP

Requirements

  • Node.js ≥ 18

  • A reachable 3x-ui panel — any version 3xui-api-client supports: modern (React, v3.x+) and legacy (Vue, v2.x), auto-detected

  • Admin credentials for that panel (username/password or an API token)

Tools

Tool

Type

Description

list_inbounds

read

List all inbounds

get_inbound

read

Get one inbound by ID

create_inbound

write

Create an inbound

update_inbound

write

Replace an inbound's config

delete_inbound

write

Delete an inbound

list_clients

read

List all clients across inbounds

get_client

read

Get one client by email

get_client_traffic

read

Get a client's traffic usage

list_online_clients

read

List currently connected clients

create_client

write

Add a client with auto-generated credentials

update_client

write

Update a client's limits/expiry/state

delete_client

write

Delete a client by email

Configuration

Set credentials via environment variables — pick one auth mode:

# Required — protocol + host + port, plus your panel's custom base path if it has
# one (most 3x-ui panels do, e.g. a random string appended for security). Example
# shape: https://your-panel.example.com:2053/aB3xR9qKzL
THREEXUI_BASE_URL=https://your-panel.example.com:2053/your-webBasePath

# Cookie auth (admin username/password)
THREEXUI_USERNAME=admin
THREEXUI_PASSWORD=your-password

# OR API token auth (skips username/password)
THREEXUI_API_TOKEN=your-token

# Optional, default "auto"
THREEXUI_PANEL_TYPE=auto   # auto | modern | legacy

Do not include a trailing /panel — the underlying client appends panel paths itself.

Use with an MCP client

No install or path needed — npx fetches and runs the published package on demand.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "3xui": {
      "command": "npx",
      "args": ["-y", "3xui-mcp"],
      "env": {
        "THREEXUI_BASE_URL": "https://your-panel.example.com:2053/your-webBasePath",
        "THREEXUI_USERNAME": "admin",
        "THREEXUI_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add --env THREEXUI_BASE_URL=https://your-panel.example.com:2053/your-webBasePath \
  --env THREEXUI_USERNAME=admin \
  --env THREEXUI_PASSWORD=your-password \
  3xui -- npx -y 3xui-mcp

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-scoped) — same schema as Claude Desktop above:

{
  "mcpServers": {
    "3xui": {
      "command": "npx",
      "args": ["-y", "3xui-mcp"],
      "env": {
        "THREEXUI_BASE_URL": "https://your-panel.example.com:2053/your-webBasePath",
        "THREEXUI_USERNAME": "admin",
        "THREEXUI_PASSWORD": "your-password"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json — note the top-level key is servers, not mcpServers:

{
  "servers": {
    "3xui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "3xui-mcp"],
      "env": {
        "THREEXUI_BASE_URL": "https://your-panel.example.com:2053/your-webBasePath",
        "THREEXUI_USERNAME": "admin",
        "THREEXUI_PASSWORD": "your-password"
      }
    }
  }
}

Running from source instead

See Contributing if you'd rather build and point your MCP config at a local checkout.

Example prompts

Once configured, you can ask your agent things like:

  • "List all my 3x-ui inbounds and how many clients are on each"

  • "Show me which clients are currently online"

  • "Add a new VLESS client called alice to inbound 3 with a 50GB limit"

  • "How much data has bob@example.com used, and when does it expire?"

  • "Extend alice's client by 30 days"

  • "Disable the client with email old-user"

  • "Create a new inbound on port 9000 with the same settings as inbound 1, just a different remark"

The agent maps these to the tool calls above — see Agent skill for the reference it uses to get field formats right.

Agent skill

skills/3xui-mcp/SKILL.md documents every tool's required/optional fields, units (GB vs bytes, ms timestamps), and common workflows for an AI agent driving this server — load it alongside the server so the agent doesn't have to guess input shapes from tool descriptions alone.

Security

  • Your panel credentials grant full admin access. THREEXUI_USERNAME/THREEXUI_PASSWORD (or THREEXUI_API_TOKEN) are only as safe as the MCP client config file they live in (e.g. claude_desktop_config.json) — protect that file with normal OS file permissions, and never commit it. Prefer an API token over username/password where your panel supports it: tokens can be scoped and revoked without invalidating a session. See 3xui-api-client's Session Security notes for how the underlying session cookie is handled.

  • create_client's generated credentials are shown once. The UUID/password/keys returned in that tool's response are not retrievable in plaintext afterward — if you're driving this via an agent, make sure it actually surfaces them to you rather than just reporting success.

  • Write tools are irreversible. delete_inbound and delete_client have no confirmation step built into the tool itself — that's the calling agent's responsibility (see SKILL.md's guidance on this). If you're driving the server directly (not through an agent), double-check IDs/emails before calling them.

Troubleshooting

Missing required environment variable: THREEXUI_BASE_URL (or _USERNAME/_PASSWORD) Your MCP client's config is missing the env block, or it's missing one of the required entries. Check the Configuration section — exactly one auth mode (username/password or API token) must be fully set.

Login fails / tools return a 401 or 404 Confirm THREEXUI_BASE_URL doesn't include a trailing /panel and does include any custom base path your panel uses. If your panel is on an unusual setup, try setting THREEXUI_PANEL_TYPE explicitly (modern or legacy) instead of auto.

A write tool succeeds but the change isn't visible in the panel UI Some panels cache dashboard views — try refreshing. If the tool's response has success: true, the change was accepted by the panel API.

Still stuck? Open an issue with the tool name, a redacted version of the error, and your panel version if known.

Contributing

See CONTRIBUTING.md for development setup, how to add a new tool, and the release process.

License

Apache-2.0

Available Tools

12 tools
create_clientCreate clientA

Create a new client on an existing inbound with auto-generated credentials (UUID/password/keys as appropriate for the protocol). Returns the generated credentials and connection info — surface these to the user, they are not retrievable again in plaintext.

Inputs: email (required), protocol (required), inboundId (required), limitIp, +2 more.

create_inboundCreate inboundA

Create a new inbound on the panel. Recommend calling get_inbound on a similar existing inbound first to see the exact shape expected for settings/streamSettings/sniffing on this panel version.

Inputs: port, enable, listen, remark, +5 more.

delete_clientDelete clientA
DestructiveIdempotent

Permanently delete a client by exact email. This cannot be undone.

Inputs: email (required).

delete_inboundDelete inboundA
DestructiveIdempotent

Permanently delete an inbound and all of its clients by ID. This cannot be undone.

Inputs: id (required).

get_clientGet client by emailA
Read-onlyIdempotent

Get full details (settings, inbound, traffic limits) for a single client by its exact email. Use list_clients first if you do not know the exact email.

Inputs: email (required).

get_client_trafficGet client traffic usageA
Read-onlyIdempotent

Get upload/download traffic totals and limits for a single client by exact email.

Inputs: email (required).

get_inboundGet inbound by IDA
Read-onlyIdempotent

Get full details of a single inbound (protocol settings, stream settings, clients, traffic) by its numeric ID. Use list_inbounds first to find the ID.

Inputs: id (required).

list_clientsList all clientsA
Read-onlyIdempotent

List every client across all inbounds on the panel, with their email, protocol, enabled state, and traffic limits.

Inputs: no named parameters.

list_inboundsList inboundsA
Read-onlyIdempotent

List every inbound configured on the 3x-ui panel, including their clients, protocol, port, and traffic stats.

Inputs: no named parameters.

list_online_clientsList currently online clientsA
Read-onlyIdempotent

List the emails of clients that are currently connected/online.

Inputs: no named parameters.

update_clientUpdate clientA
DestructiveIdempotent

Update an existing client's traffic limit, expiry, or enabled state. Only the fields you pass are changed; everything else on the client is preserved.

Inputs: clientId (required), inboundId (required), enable, limitIp, +3 more.

update_inboundUpdate inboundA
DestructiveIdempotent

Update an existing inbound by ID. This replaces the inbound configuration, so fetch it with get_inbound first and merge your changes into the full object rather than sending a partial one.

Inputs: id (required), port, enable, listen, +6 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 12 tools

    Disambiguation5/5

    Tools are cleanly divided between inbound management and client management, with each tool targeting a distinct resource-action pair. Even within clients, get_client and get_client_traffic are clearly differentiated by scope, eliminating any ambiguity.

    Naming Consistency5/5

    All tools follow a consistent verb_noun snake_case pattern (list/get/create/update/delete), applied uniformly across both inbounds and clients. This makes the API highly predictable and easy to navigate.

    Tool Count5/5

    With 12 tools, the server is well-scoped for managing two primary resources (inbounds and clients). Each tool has a clear purpose and none feel redundant, falling comfortably within the ideal range.

    Completeness5/5

    The tool surface covers the full lifecycle for both inbounds and clients, including creation, retrieval, update, deletion, and listing. Additional capabilities like traffic stats and online status round out the domain without obvious gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Enables AI agents to manage server infrastructure through the 1Panel API, including Docker containers, databases, and system monitoring. It provides tools for website management, file operations, and application deployment via natural language commands.
      15
      35 npm
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      Enables MCP clients like Claude Code, Claude Desktop, or Cursor to read and manage Remnawave 3.x VPN panel resources — users, nodes, hosts, config profiles, squads, subscription templates, billing, and HWID devices — through the panel's REST API, with contract-driven tool schemas, numeric user IDs, multi-panel config lookup, and an optional readonly mode.
      204
      13 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables managing 3x-ui panels through their current API, including creating and updating clients across inbounds, monitoring online clients, and accessing panel features like nodes, routing, and backups via runtime-discovered API tools.
      MIT