Singleplayer

Put WorldAPI in your game, and an AI agent can answer questions about the world you're playing right now: where the nearest village is, what's in your chests, how many diamonds you've mined, what you're looking at. It takes about two minutes.

1. Install the mod

WorldAPI runs on Fabric and NeoForge for Minecraft 26.3, with Java 25.

1. In your launcher, make a profile with Fabric Loader and Fabric API, or with NeoForge, for 26.3. Modrinth App, Prism Launcher, and CurseForge do it in a few clicks.
2. Put the jar into the profile's mods/ folder: worldapi-fabric.jar or worldapi-neoforge.jar, or install WorldAPI from Modrinth right in the launcher.
3. Start the game and open a world, new or old.

The chat greets you once: WorldAPI is on. /worldapi connect shows its address with buttons that copy the token and the line for Claude Code. You don't need cheats for it.

2. Connect your AI client

minecraft-mcp finds the open world by itself, so it needs no address and no token.

• Claude Code: claude mcp add minecraft -- npx -y @mairwunnx/minecraft-mcp.
• Claude Desktop: install the .mcpb bundle from minecraft-mcp's releases and leave “WorldAPI URL” empty.
• Another MCP client: run npx -y @mairwunnx/minecraft-mcp over stdio without WORLDAPI_URL.

Node.js 22 or newer must be installed for npx.

3. Ask

• “Where's the nearest village, and how do I get there from here?”
• “What am I looking at?”
• “Which of my chests near the base has iron?”
• “How long have I played this world, and how did I die last?”
• “Set the time to morning and clear the weather.”

The agent gets everything WorldAPI's admin group may do, the same as the token in config/worldapi/config.yml: it reads the world and can change it, cheats or not. It asks you before anything destructive. To keep it read-only, set WORLDAPI_READ_ONLY=1 in the MCP setup.

How it works

• A world, a server. The game runs a small server under every world you open. WorldAPI starts with it and listens on 127.0.0.1:8110, and stops when you leave, freeing the port. With a second game open, the next world takes 8111, and so on up to 8119.
• Finding the game. While a world is open, WorldAPI writes ~/.worldapi/local/<port>.json with its address and token, readable by you only, and removes it when you leave. minecraft-mcp reads that folder on every call, so it follows you from world to world. Between worlds it answers that no world is open.
• Each world its own data. The event history, play sessions, and tokens you make live in the save's worldapi/ folder. Copy a world, and the copy has them; delete it, and they go with it. The config and its token in config/worldapi/ serve every world.
• Only this computer. A singleplayer world never listens beyond 127.0.0.1, and answers only requests that name it as localhost or 127.0.0.1. A web page can't reach it, and neither can a LAN guest. Opening the world to LAN changes nothing for the API; GET /server then says "lan": true.
• What clients see. GET /server says "platform": "fabric" or "neoforge", "side": "integrated", whether the world allows cheats, and whether the game is paused. Worlds are overworld, the_nether, and the_end.

The admin panel

/worldapi admin gives a code for a panel account in this world, with a link that opens http://127.0.0.1:8110/admin/ and fills it in. Pick a password, and the panel shows your world live. Restarting and stopping aren't there: you leave a world in game.

Graphs

Monitoring runs minecraft-exporter beside the game, and Prometheus and Grafana in Docker, with a dashboard row for your world.

When something's off

• “No Minecraft world with WorldAPI is open.” Open a world, or check the log for Listening on 127.0.0.1: and a line about WorldAPI.
• The agent reached another game. With two games open, minecraft-mcp takes the world opened last. To pick one, set WORLDAPI_URL=http://127.0.0.1:8111/api/v1 and WORLDAPI_TOKEN to the token from config/worldapi/config.yml.
• A container can't reach it. That's on purpose: WorldAPI listens on this computer only. Run the client beside the game.

Next: MCP, or First steps for the API itself.