Singleplayer

Singleplayer

Ask an agent about the world you're playing right now. With WorldAPI's Fabric or NeoForge mod in your game, minecraft-mcp needs no address and no token: it finds the open world by itself.

1. Put WorldAPI 4.2.0 or newer in your game's mods/ folder and open a world. WorldAPI's Singleplayer page has the details.

2. Add minecraft-mcp without WORLDAPI_URL:

   claude mcp add minecraft -- npx -y @mairwunnx/minecraft-mcp

   In Claude Desktop, install the bundle and leave “WorldAPI URL” empty. In another client, start npx -y @mairwunnx/minecraft-mcp with no env at all.

3. Ask “what am I looking at?” or “where's the nearest village?”.

How it finds the game

While a world is open, WorldAPI writes ~/.worldapi/local/<port>.json with its address and token, readable by you only. minecraft-mcp reads that folder on every call and takes the world opened last whose game still runs. So it follows you when you leave one world and open another, and it can start before the game does.

While no world is open, tools answer no_world: “No Minecraft world with WorldAPI is open.” Open one, and the next call reaches it.

What the agent gets

The world's own token belongs to WorldAPI's admin group: the agent reads everything and may change the world, the players, and the game rules, cheats or not, and asks you before anything destructive. WORLDAPI_READ_ONLY=1 keeps it to looking. Java scripts aren't there: WorldAPI runs them on Paper only.

The agent also learns it's in singleplayer: you're the world's owner and the player it talks about, worlds are overworld, the_nether, and the_end, and get_server_status says whether the game is paused or open to LAN and whether the world allows cheats.

Settings

• WORLDAPI_PLAYER isn't needed alone in a world, but helps when LAN friends join.
• WORLDAPI_LOCAL_DIR points minecraft-mcp at another folder than ~/.worldapi/local.
• WORLDAPI_URL and WORLDAPI_TOKEN turn the search off and pin one address, such as a second game's http://127.0.0.1:8111/api/v1.

Next: Configuration.