3xui-mcp

MCP (Model Context Protocol) server for the 3x-ui panel, built on 3xui-api-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 — extend src/tools/ if you need them.

Tools

Related MCP server: Open WebUI MCP Server

Configuration

Set credentials via environment variables — pick one auth mode:

# Required
THREEXUI_BASE_URL=https://your-panel.example.com

# 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

Build & run

npm install
npm run build
npm start

Use with an MCP client

Add to your client's MCP config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "3xui": {
      "command": "node",
      "args": ["/absolute/path/to/3xui-mcp/dist/index.js"],
      "env": {
        "THREEXUI_BASE_URL": "https://your-panel.example.com",
        "THREEXUI_USERNAME": "admin",
        "THREEXUI_PASSWORD": "your-password"
      }
    }
  }
}

Once published to npm, command/args can be replaced with "npx" / ["-y", "3xui-mcp"].

Test locally

npm run inspector

Opens the MCP Inspector against this server.

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.