3xui-mcp

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, 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 — extend src/tools/ if you need them.

Tools

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

Use with an MCP client

Add to your client's MCP config (e.g. Claude Desktop claude_desktop_config.json). No install or path needed — npx fetches and runs the published package on demand:

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

Running from source instead

If you're developing this server locally rather than using the published package:

npm install
npm run build

Then point your MCP config at the built file directly — replace the path below with wherever you actually cloned this repo:

{
  "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"
      }
    }
  }
}

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.

Release process

Versioning lives in GitHub Releases, not in manual package.json commits:

1. Draft a new GitHub Release with tag vX.Y.Z (must match vX.Y.Z or vX.Y.Z-prerelease).
2. Publishing the release triggers .github/workflows/release.yml, which builds, sets package.json's version to match the tag, and runs npm publish.
3. If the release event doesn't fire the workflow (GitHub occasionally misses it), trigger it manually: Actions → Publish to npm → Run workflow, entering the same tag.

Requires a repo secret NPM_TOKEN — an npm access token with publish rights and 2FA bypass enabled for automation, added under Settings → Secrets and variables → Actions.

The version checked into package.json on main is a starting point only; the release tag is the source of truth for what actually gets published. Bump it locally too when convenient so the repo doesn't drift too far from the last published version, but the workflow doesn't depend on it matching.