Numen MCP
- By
Expose your Minecraft Numen companions over MCP — an external agent like Claude takes control and drives them directly. Requires Numen. Fabric + NeoForge.
Numen MCP
Turn your Numen companions into tools an external AI can drive. Numen MCP runs a small Model Context Protocol server inside your game client, so an agent like Claude can list your companions, take control of one, and call its tools directly — Claude becomes the brain, the companion is its hands and eyes.
Multi-loader (Fabric + NeoForge), Minecraft 1.21.1.
⚠️ This mod does nothing on its own. It requires Numen (the companion engine) and an external MCP client (e.g. Claude Code / Claude Desktop) to connect to it. See Requirements below.
How it differs from a normal Numen companion
A Numen companion normally thinks with its own built-in LLM. Numen MCP lets an outside brain skip that LLM entirely:
- Claude is the player. It reads the world through perception tools (
get_self_status,scan_blocks, …) and decides every action itself. - No Numen API key needed for this mode — Claude does the reasoning; the companion just executes tools.
- Parallel fleets. Every call is addressed to one companion, so one agent can drive several companions at once.
- Survival-legitimate. The exposed tools are the same ones the built-in brain uses — mine, move, place, craft. Nothing conjures items from nothing.
Requirements
- Numen 0.0.4+ — the companion engine (bundles the numen-api runtime this mod drives).
- Client-side. Companions and their tools live in the owner's game client, so install it there.
- An MCP client — Claude Code (native HTTP) or Claude Desktop (via
mcp-remote).
Setup
- Install Numen + Numen MCP in your client. Launch once; it writes
config/numen/mcp_server.jsonand printsMCP server up on http://127.0.0.1:8765/mcpwhen listening. - Point your MCP client at it:
- Claude Code —
.mcp.jsonin your project:{ "mcpServers": { "numen": { "type": "http", "url": "" rel="noopener nofollow" target="_blank">http://127.0.0.1:8765/mcp" } } } - Claude Desktop —
claude_desktop_config.json(needs Node/npx):{ "mcpServers": { "numen": { "command": "npx", "args": ["mcp-remote", "http://127.0.0.1:8765/mcp"] } } }
- Claude Code —
- Summon a companion in-game, then in your agent:
list_companions→acquire_companion→ drive it. The server only listens while the game is running.
Tools
| Tool | What it does |
|---|---|
list_companions |
List your live companions (name + id) |
acquire_companion |
Take control — pauses the built-in brain, frees the body |
release_companion |
Hand the companion back to its built-in brain |
| (engine tools) | Every Numen body/perception tool (get_self_status, scan_blocks, auto_mine, move_to, place_block, …), each taking a companion argument |
On connect, the server hands the agent a short briefing (MCP's instructions) — what Numen is and the acquire → perceive → act → release loop — so any MCP client works out of the box.
Multiplayer
Works on remote servers. Numen MCP is client-only and drives through Numen's existing client→server protocol — the same packets the built-in brain uses. The server needs Numen installed (as it already does for companions to exist); it does not need Numen MCP. The server owner-checks every action, so you can only drive companions you own.
Networking & privacy
Numen MCP opens a local, loopback-only HTTP endpoint (127.0.0.1:8765 by default) for your MCP client to connect to. Nothing is exposed to the internet, and no data leaves your machine. It's fully configurable in config/numen/mcp_server.json:
enabled— master switch.host/port— bind address (loopback by default).token— optional bearer token required on every request.call_timeout_seconds— how long a tool call waits before timing out.hidden_tools— engine tools not exposed to the external agent.
Links
- Source & docs: https://github.com/Dwinovo/numen-mcp
- Numen (the mod): https://github.com/Dwinovo/minecraft-numen
MIT licensed.
The Numen MCP Team
Owner
