3xui-mcp
This server lets AI agents manage a 3x-ui VPN panel by combining read-only queries with full CRUD operations for inbounds and clients.
Inbound reads: list all inbounds, get one inbound by ID, including protocol, port, clients, and traffic.
Inbound management: create, update (replace full config), and permanently delete inbounds.
Client reads: list all clients across inbounds, get a client by email, view traffic usage, and list currently online clients.
Client management: create clients with auto-generated credentials, update limits/expiry/enabled state, and delete clients by email.
Safety/scoping: intentionally limited to inbounds/clients; nodes, groups, backups, Xray config, and panel settings are out of scope.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@3xui-mcp Create a new client with 100GB quota"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-clientsupports: modern (React, v3.x+) and legacy (Vue, v2.x), auto-detectedAdmin credentials for that panel (username/password or an API token)
Tools
Tool | Type | Description |
| read | List all inbounds |
| read | Get one inbound by ID |
| write | Create an inbound |
| write | Replace an inbound's config |
| write | Delete an inbound |
| read | List all clients across inbounds |
| read | Get one client by email |
| read | Get a client's traffic usage |
| read | List currently connected clients |
| write | Add a client with auto-generated credentials |
| write | Update a client's limits/expiry/state |
| 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 | legacyDo 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-mcpCursor
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
aliceto inbound 3 with a 50GB limit""How much data has
bob@example.comused, 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(orTHREEXUI_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. See3xui-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_inboundanddelete_clienthave no confirmation step built into the tool itself — that's the calling agent's responsibility (seeSKILL.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
Available Tools
12 toolscreate_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 clientADestructiveIdempotent
Permanently delete a client by exact email. This cannot be undone.
Inputs: email (required).
delete_inboundDelete inboundADestructiveIdempotent
Permanently delete an inbound and all of its clients by ID. This cannot be undone.
Inputs: id (required).
get_clientGet client by emailARead-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 usageARead-onlyIdempotent
Get upload/download traffic totals and limits for a single client by exact email.
Inputs: email (required).
get_inboundGet inbound by IDARead-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 clientsARead-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 inboundsARead-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 clientsARead-onlyIdempotent
List the emails of clients that are currently connected/online.
Inputs: no named parameters.
update_clientUpdate clientADestructiveIdempotent
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 inboundADestructiveIdempotent
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
Scored across 12 tools
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.
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.
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.
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
Related MCP Connectors
Manage Chatbase agents, sources, conversations and help-desk tickets.
Connect your AI agent to 300+ methods and 100+ live tools
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables 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.1535 npmMIT
- AlicenseAqualityDmaintenanceEnables AI agents to safely read, audit, and manage Clash Verge Rev / Mihomo configuration with read-only and controlled runtime operations.668 npmMIT
- AlicenseCqualityBmaintenanceEnables 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.20413 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables 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