{"_id":"3xui-mcp","_rev":"3-68c3f7c94dd54791607f57d095ae8521","name":"3xui-mcp","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"3xui-mcp","version":"0.1.0","keywords":["mcp","model-context-protocol","3x-ui","3xui","xray","vpn"],"author":{"url":"https://github.com/iamhelitha","name":"Helitha Guruge"},"license":"Apache-2.0","_id":"3xui-mcp@0.1.0","maintainers":[{"name":"iamhelitha","email":"helithalochana@gmail.com"}],"homepage":"https://github.com/iamhelitha/3xui-mcp#readme","bugs":{"url":"https://github.com/iamhelitha/3xui-mcp/issues"},"bin":{"3xui-mcp":"dist/index.js"},"dist":{"shasum":"fe3e1e17c679508cd5d9d20523ac7efeffd9868b","tarball":"https://registry.npmjs.org/3xui-mcp/-/3xui-mcp-0.1.0.tgz","fileCount":8,"integrity":"sha512-2KQv+YYXy9lsPMg1ejzyTPhI2cJiAgO+Q3kREEv7d1nsGqQb2A9ZfnCub0nQyy1PR27MIHAfkh1hnx0WdhOfFg==","signatures":[{"sig":"MEQCIBB1suraLl7O4KQqLHu4Hu2lpLdZe+JXanv8uOLEEQ6yAiAd3T/OErCH3vp054evks3qNhgDLpmpfO/j6zBcZWL8aw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30391},"main":"dist/index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"f4f4e375dc9806be22428ae325767c05e941deb0","scripts":{"dev":"tsc --watch","build":"tsc","start":"node dist/index.js","inspector":"npx @modelcontextprotocol/inspector node dist/index.js"},"_npmUser":{"name":"iamhelitha","email":"helithalochana@gmail.com"},"repository":{"url":"git+https://github.com/iamhelitha/3xui-mcp.git","type":"git"},"_npmVersion":"11.19.0","description":"MCP server exposing 3x-ui panel read operations and inbound/client CRUD to LLM agents, built on 3xui-api-client","directories":{},"_nodeVersion":"25.7.0","dependencies":{"zod":"^3.24.0","3xui-api-client":"^3.2.0","@modelcontextprotocol/sdk":"^1.30.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/3xui-mcp_0.1.0_1787827640973_0.4566316624194149","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"3xui-mcp","version":"0.1.1","keywords":["mcp","model-context-protocol","3x-ui","3xui","xray","vpn"],"author":{"url":"https://github.com/iamhelitha","name":"Helitha Guruge"},"license":"Apache-2.0","_id":"3xui-mcp@0.1.1","maintainers":[{"name":"iamhelitha","email":"helithalochana@gmail.com"}],"homepage":"https://github.com/iamhelitha/3xui-mcp#readme","bugs":{"url":"https://github.com/iamhelitha/3xui-mcp/issues"},"bin":{"3xui-mcp":"dist/index.js"},"dist":{"shasum":"1db01585663dd576828143ca370ddb9b631f90aa","tarball":"https://registry.npmjs.org/3xui-mcp/-/3xui-mcp-0.1.1.tgz","fileCount":8,"integrity":"sha512-ZFx7g8TWclYJCheqc72RE5nFwQgEsr9hdGtBX8u/byco4RtkAJL7TJcxJJ0XPZoIbjxznLQCaa/jj6la+SvtRA==","signatures":[{"sig":"MEUCIAtP8Y7XTFBFbwF85EgFuWNMBcGsbKcLBeFFUnxzCy1eAiEAtNKMOgVL7azHiySjnLkkx9+gariQsYisjJNCuLU/DF0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30886},"main":"dist/index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"bfee2c8b9674d39fa6d30fbdd12a136cd0b3731e","scripts":{"dev":"tsc --watch","build":"tsc","start":"node dist/index.js","inspector":"npx @modelcontextprotocol/inspector node dist/index.js"},"_npmUser":{"name":"iamhelitha","email":"helithalochana@gmail.com"},"repository":{"url":"git+https://github.com/iamhelitha/3xui-mcp.git","type":"git"},"_npmVersion":"11.19.0","description":"MCP server exposing 3x-ui panel read operations and inbound/client CRUD to LLM agents, built on 3xui-api-client","directories":{},"_nodeVersion":"25.7.0","dependencies":{"zod":"^3.24.0","3xui-api-client":"^3.2.0","@modelcontextprotocol/sdk":"^1.30.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/3xui-mcp_0.1.1_1787828074555_0.5636346761770292","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"3xui-mcp","version":"0.1.2","description":"MCP server exposing 3x-ui panel read operations and inbound/client CRUD to LLM agents, built on 3xui-api-client","type":"module","main":"dist/index.js","bin":{"3xui-mcp":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsc --watch","inspector":"npx @modelcontextprotocol/inspector node dist/index.js"},"keywords":["mcp","model-context-protocol","3x-ui","3xui","xray","vpn"],"author":{"name":"Helitha Guruge","url":"https://github.com/iamhelitha"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/iamhelitha/3xui-mcp.git"},"bugs":{"url":"https://github.com/iamhelitha/3xui-mcp/issues"},"homepage":"https://github.com/iamhelitha/3xui-mcp#readme","engines":{"node":">=18.0.0"},"dependencies":{"3xui-api-client":"^3.2.0","@modelcontextprotocol/sdk":"^1.30.0","zod":"^3.24.0"},"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.10.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"gitHead":"81a7fb24e18e2847d0ece7d47b771bae9fc8ecd8","_id":"3xui-mcp@0.1.2","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-fL+Xr9Tce5pRQBuOai9WQBPj99n/lt9Iugm1k1DR3EaFPTIW8+gbp3si+U1+0khXSZe4IvZenbGrmz7Byc1dzA==","shasum":"adf75e34bad53cbd56c4ade8087c5a377645a2f2","tarball":"https://registry.npmjs.org/3xui-mcp/-/3xui-mcp-0.1.2.tgz","fileCount":8,"unpackedSize":31983,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/3xui-mcp@0.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIB4WlLlHs26d7ivRV5p+ZXCwVCmT3snbElBQ3FTD58jnAiEAuoouCeMxVWmp2dNlfAskbXPMZmz9DyHhVtCt8rpHLNw="}]},"_npmUser":{"name":"iamhelitha","email":"helithalochana@gmail.com"},"directories":{},"maintainers":[{"name":"iamhelitha","email":"helithalochana@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/3xui-mcp_0.1.2_1787828974996_0.4589969125381774"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-27T10:47:20.775Z","modified":"2026-08-27T11:09:35.620Z","0.1.0":"2026-08-27T10:47:21.119Z","0.1.1":"2026-08-27T10:54:34.670Z","0.1.2":"2026-08-27T11:09:35.158Z"},"bugs":{"url":"https://github.com/iamhelitha/3xui-mcp/issues"},"author":{"name":"Helitha Guruge","url":"https://github.com/iamhelitha"},"license":"Apache-2.0","homepage":"https://github.com/iamhelitha/3xui-mcp#readme","keywords":["mcp","model-context-protocol","3x-ui","3xui","xray","vpn"],"repository":{"type":"git","url":"git+https://github.com/iamhelitha/3xui-mcp.git"},"description":"MCP server exposing 3x-ui panel read operations and inbound/client CRUD to LLM agents, built on 3xui-api-client","maintainers":[{"name":"iamhelitha","email":"helithalochana@gmail.com"}],"readme":"

\n \"3xui-mcp\n

\n\n

\n \"npm\n \"npm\n \"license\"\n \"node\n \"GitHub\n

\n\n# 3xui-mcp\n\nMCP (Model Context Protocol) server for the [3x-ui](https://github.com/MHSanaei/3x-ui) panel, built on [`3xui-api-client`](https://www.npmjs.com/package/3xui-api-client). Manage inbounds and clients on your VPN panel directly from Claude, Cursor, or any MCP-compatible client.\n\nScoped 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.\n\n## Tools\n\n| Tool | Type | Description |\n|---|---|---|\n| `list_inbounds` | read | List all inbounds |\n| `get_inbound` | read | Get one inbound by ID |\n| `create_inbound` | write | Create an inbound |\n| `update_inbound` | write | Replace an inbound's config |\n| `delete_inbound` | write | Delete an inbound |\n| `list_clients` | read | List all clients across inbounds |\n| `get_client` | read | Get one client by email |\n| `get_client_traffic` | read | Get a client's traffic usage |\n| `list_online_clients` | read | List currently connected clients |\n| `create_client` | write | Add a client with auto-generated credentials |\n| `update_client` | write | Update a client's limits/expiry/state |\n| `delete_client` | write | Delete a client by email |\n\n## Configuration\n\nSet credentials via environment variables — pick **one** auth mode:\n\n```bash\n# Required\nTHREEXUI_BASE_URL=https://your-panel.example.com\n\n# Cookie auth (admin username/password)\nTHREEXUI_USERNAME=admin\nTHREEXUI_PASSWORD=your-password\n\n# OR API token auth (skips username/password)\nTHREEXUI_API_TOKEN=your-token\n\n# Optional, default \"auto\"\nTHREEXUI_PANEL_TYPE=auto # auto | modern | legacy\n```\n\n## Use with an MCP client\n\nAdd 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:\n\n```json\n{\n \"mcpServers\": {\n \"3xui\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"3xui-mcp\"],\n \"env\": {\n \"THREEXUI_BASE_URL\": \"https://your-panel.example.com\",\n \"THREEXUI_USERNAME\": \"admin\",\n \"THREEXUI_PASSWORD\": \"your-password\"\n }\n }\n }\n}\n```\n\n### Running from source instead\n\nIf you're developing this server locally rather than using the published package:\n\n```bash\nnpm install\nnpm run build\n```\n\nThen point your MCP config at the built file directly — replace the path below with wherever you actually cloned this repo:\n\n```json\n{\n \"mcpServers\": {\n \"3xui\": {\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/3xui-mcp/dist/index.js\"],\n \"env\": {\n \"THREEXUI_BASE_URL\": \"https://your-panel.example.com\",\n \"THREEXUI_USERNAME\": \"admin\",\n \"THREEXUI_PASSWORD\": \"your-password\"\n }\n }\n }\n}\n```\n\n## Test locally\n\n```bash\nnpm run inspector\n```\n\nOpens the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) against this server.\n\n## Agent skill\n\n[`skills/3xui-mcp/SKILL.md`](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.\n\n## Release process\n\nVersioning lives in GitHub Releases, not in manual `package.json` commits:\n\n1. Draft a [new GitHub Release](https://github.com/iamhelitha/3xui-mcp/releases/new) with tag `vX.Y.Z` (must match `vX.Y.Z` or `vX.Y.Z-prerelease`).\n2. Publishing the release triggers [`.github/workflows/release.yml`](.github/workflows/release.yml), which builds, sets `package.json`'s version to match the tag, and runs `npm publish`.\n3. 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.\n\nRequires 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**.\n\nThe 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.\n","readmeFilename":"README.md"}