worldbox-mcp¶
Give your AI agent god-mode in WorldBox. Spawn dragons. Burn continents. Run civilization speedruns. From a conversation.
worldbox-mcp is an open-source bridge that lets any MCP-compatible AI client — Claude Code, OpenCode, Codex, Cursor, Continue, and more — directly control the live game.
It ships as two open-source components:
WorldBoxBridge— a BepInEx plugin (C#) injected into the running game that exposes an authenticated HTTP API to the game's internals.worldbox-mcp— a Python MCP server distributed via PyPI (uvx worldbox-mcp) that translates MCP tool calls into HTTP requests.
Quick links¶
- 🚀 Install — pick your AI client
- 🏗 Architecture — how the two halves talk to each other
- 📚 Command reference — every tool, auto-generated
- 👥 Multi-agent sessions — N AIs on one world (v0.3+)
- 🧩 Compatibility — WorldBox × mod version matrix
- 🤝 Contributing — code, docs, issues
Twenty-six tools across six categories¶
| Category | Tools |
|---|---|
| Meta | worldbox_health, worldbox_capabilities, worldbox_whoami, worldbox_session_info, worldbox_turn_advance, worldbox_objective_status |
| Discovery | worldbox_list_tiles (20), worldbox_list_actors (322), worldbox_list_powers (339) |
| Action | worldbox_invoke_power, worldbox_spawn, worldbox_paint_tile |
| Read | worldbox_get_world_state, worldbox_get_tile, worldbox_list_kingdoms, worldbox_list_cities, worldbox_query_actors, worldbox_screenshot |
| Control | worldbox_pause, worldbox_resume, worldbox_set_speed, worldbox_generate_world, worldbox_save_world, worldbox_load_world |
| Bus | worldbox_send_message, worldbox_recv_messages |
See command-reference.md for arguments + return shapes and multi-agent.md for putting N AIs on the same world.
Design principles¶
- 100% game coverage through three generic action primitives (
paint_tile,spawn,invoke_power) backed by the game's own asset registry — see protocol.md. - Survives game updates: zero static binding to WorldBox internals; everything resolves through cached reflection with explicit logging when a symbol disappears.
- Local-only by design: HTTP bound to
127.0.0.1, per-install random auth token, no telemetry. - Production-grade: typed, tested, signed releases, automated CI/CD.
worldbox-mcp is an unofficial community project and is not affiliated with or endorsed by the WorldBox developers.