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

1. Install Numen + Numen MCP in your client. Launch once; it writes config/numen/mcp_server.json and prints MCP server up on http://127.0.0.1:8765/mcp when listening.
2. Point your MCP client at it:
   • Claude Code — .mcp.json in 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"] } } }
     

3. 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

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.