jx3box-mcp
by zenenznze
README.md
# jx3box-mcp
Read-only [MCP](https://modelcontextprotocol.io) server (and a small CLI) for the
public **JX3BOX** (魔盒,剑网3 / JX3) endpoints: posts, macro guides, build (配装)
pages and Node v2 game data.
- **No API key, account, cookie or token.** Every request goes to the public
JX3BOX APIs with a plain `User-Agent`. Nothing is collected or stored.
- **No dependencies.** Pure Node.js (>= 18.17) ESM; `npx` or a global install is enough.
- **Read-only.** The tools fetch and parse; they never write to JX3BOX.
Not affiliated with or endorsed by JX3BOX / 剑网3. Data and rate limits belong to
JX3BOX; respect their terms and do not hammer the API.
## Install
```bash
npx -y jx3box-mcp # MCP stdio server, no install step
# or
npm install -g jx3box-mcp
```
## Use as an MCP server
MCP client configuration (Claude Desktop, Codex, Cursor, Magpie Library, …):
```json
{
"mcpServers": {
"jx3box": {
"command": "npx",
"args": ["-y", "jx3box-mcp"]
}
}
}
```
Magpie Library has the same shape:
```bash
magpie library mcp add jx3box npx -y jx3box-mcp
```
Tools:
| Tool | What it returns |
| --- | --- |
| `jx3box_get_post` | A post by ID or `jx3box.com/macro|bps|pz/ID` URL: metadata, full text, raw HTML, macro/build fields |
| `jx3box_get_macro` | A macro post's scripts, instructions, talent data and metadata |
| `jx3box_search` | CMS search over posts: keyword, kind (`all|macro|bps|pz`), subtype, season, pagination |
| `jx3box_get_build` | A build (配装) page by post URL or ID |
| `jx3box_get_game_data` | Documented `/api/node/v2` game data, e.g. `endpoint: "item"` |
The server speaks MCP over stdio (newline-delimited JSON-RPC); `Content-Length`
framed clients are accepted too.
## CLI
```bash
npx -y jx3box-mcp --help # MCP server help
npx -y jx3box get 110420
npx -y jx3box get https://www.jx3box.com/macro/110420 --format json
npx -y jx3box search macro --keyword 冰心诀 --season 苍生铸世 --limit 10
npx -y jx3box search all --keyword 配装 --format json
```
## Data sources
- CMS posts: `https://cms.jx3box.com/api/cms/post/{id}`, `/posts` (search),
`/app/pz/{id}` (builds)
- Game data: `https://node.jx3box.com/api/node/v2/{endpoint}`
HTTP and API errors are surfaced as tool errors; there is no automatic retry and
no attempt to bypass access controls.
## Development
```bash
npm test # unit tests, no network
```
The tests inject a fake `fetch`, so they never touch JX3BOX.
## License
MIT. See [LICENSE](LICENSE).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues