Minecraft — Claude Code MCP server: features and setup
This MCP server connects an AI agent to Minecraft through WorldAPI, so it can inspect the world and carry out actions allowed by its token. Use it to check or manage a server from chat.
claude mcp add --env WORLDAPI_URL=<WORLDAPI_URL> --env WORLDAPI_TOKEN=<WORLDAPI_TOKEN> --env WORLDAPI_READ_ONLY=<WORLDAPI_READ_ONLY> --transport stdio minecraft -- npx -y @mairwunnx/minecraft-mcpWhat Minecraft does
The agent can access information about players, worlds, blocks, chests, entities, recipes, settings, and logs. Available operations include running commands and Java scripts, inspecting inventories, and editing configuration when the token permits it. It can also report events such as a player joining.
A Paper, Fabric, or NeoForge server needs WorldAPI installed; for singleplayer, install the WorldAPI mod in the game world. The MCP server connects through Claude Code, Codex, Cursor, and other listed MCP clients. Token permissions shape what the agent can do: read-only mode hides write operations, while a viewer token exposes 17 tools for viewing data. WorldAPI must be running for the connection to work.
What it helps with
- check which players are online and locate them
- inspect server status and investigate lag
- read server configuration and logs
- change an allowed configuration value while retaining its comments
- get notified when a player joins
Example prompts for the agent
- Show me who is online and where each player is.
- Inspect the logs and find out why the server is lagging.
- Tell me when Steve joins the server.
How to install Minecraft
Platform CLI
claude mcp add --env WORLDAPI_URL=<WORLDAPI_URL> --env WORLDAPI_TOKEN=<WORLDAPI_TOKEN> --env WORLDAPI_READ_ONLY=<WORLDAPI_READ_ONLY> --transport stdio minecraft -- npx -y @mairwunnx/minecraft-mcpReplace <…> with your own values
Platform CLI
codex mcp add minecraft --env WORLDAPI_URL=<WORLDAPI_URL> --env WORLDAPI_TOKEN=<WORLDAPI_TOKEN> --env WORLDAPI_READ_ONLY=<WORLDAPI_READ_ONLY> -- npx -y @mairwunnx/minecraft-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"minecraft": {
"command": "npx",
"args": [
"-y",
"@mairwunnx/minecraft-mcp"
],
"env": {
"WORLDAPI_URL": "<WORLDAPI_URL>",
"WORLDAPI_TOKEN": "<WORLDAPI_TOKEN>",
"WORLDAPI_READ_ONLY": "<WORLDAPI_READ_ONLY>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"minecraft": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@mairwunnx/minecraft-mcp"
],
"env": {
"WORLDAPI_URL": "<WORLDAPI_URL>",
"WORLDAPI_TOKEN": "<WORLDAPI_TOKEN>",
"WORLDAPI_READ_ONLY": "<WORLDAPI_READ_ONLY>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e WORLDAPI_URL=<WORLDAPI_URL> -e WORLDAPI_TOKEN=<WORLDAPI_TOKEN> -e WORLDAPI_READ_ONLY=<WORLDAPI_READ_ONLY> minecraft npx -y @mairwunnx/minecraft-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Minecraft
How do I install Minecraft in Claude Code?
First run claude mcp add minecraft-mcp -e WORLDAPI_URL=<WORLDAPI_URL> -e WORLDAPI_TOKEN=<WORLDAPI_TOKEN> -- npx -y @mairwunnx/minecraft-mcp. Before that, install WorldAPI on a Paper, Fabric, or NeoForge server and create a token with /worldapi token create agent.
What does the Minecraft MCP server do?
It connects an AI agent to Minecraft through WorldAPI. The agent can inspect world data and perform actions permitted by its token.
What is required to connect it to Minecraft?
Install WorldAPI on a Paper, Fabric, or NeoForge server and provide a token. For singleplayer, install the WorldAPI mod in the game world.
