minecraft-rcon-mcp

An MCP server that exposes a Minecraft Java Edition server over RCON as a tool, plus an optional in-game AI chat listener: players type ai <question> in chat and Claude answers in-game, using RCON to read live world state.

It is configured entirely through environment variables, so it is independent of any particular server, world, or Minecraft version.

Features

• `run_command` tool — run any Minecraft server command via RCON and return

the response. Use it from any MCP client (Claude Code, VS Code / Copilot, etc.) to inspect or modify the live world.

• In-game AI chat — a background thread tails the server log; chat messages

prefixed with a configurable trigger (ai by default) are answered by Claude via the Anthropic API, with an agentic RCON tool-use loop and a rolling context window. Responses are posted back with /tellraw.

• Persistent memory — the in-game agent reads two git-tracked memory files

into its context each request and can append to them with a remember tool, so it accumulates knowledge across sessions instead of relying only on the rolling chat window. See Persistent memory.

• `get_ai_chat_status` tool — report listener health, history size, model,

log path, and memory configuration.

Requirements

• Python 3.14+
• A Minecraft server with RCON enabled (enable-rcon=true in server.properties)
• An Anthropic API key (only if you use the in-game AI chat feature)

Install

pip install git+https://github.com/scotteratigan/minecraft-rcon-mcp

Or, for local development / use from a sibling repo:

pip install -e path/to/minecraft-rcon-mcp

Run

minecraft-rcon-mcp          # console entry point
python -m minecraft_rcon_mcp   # equivalent

The server speaks MCP over stdio, so it is normally launched by an MCP client rather than by hand. Example client config (.vscode/mcp.json):

{
  "servers": {
    "minecraft-rcon": {
      "type": "stdio",
      "command": "/path/to/.venv/Scripts/python.exe",
      "args": ["-m", "minecraft_rcon_mcp"],
      "env": {
        "RCON_HOST": "localhost",
        "RCON_PORT": "25575",
        "RCON_PASSWORD": "your-rcon-password",
        "LOG_PATH": "/path/to/server/logs/latest.log"
      }
    }
  }
}

Provide ANTHROPIC_API_KEY in the launching environment (not in committed files) if you want the in-game AI chat.

Configuration

The run_command + remember tools are always available. Two more — list_scripts and run_script — dispatch the Python toolbox (structure builders, world queries) without one MCP tool per script; see Scripts & recipes. They're also exposed to the in-game chat agent, so players can ask it to build things.

Persistent memory

The in-game AI agent keeps two separate memory stores, both intended to be version-controlled, so it accumulates knowledge across sessions. The split is deliberate — each store lives in a different repo:

How it works:

• Read — on every chat request, both files are read fresh and appended to the

system prompt under a # Persistent memory heading. Editing a file (by hand or by the agent) takes effect on the next message; no restart needed.

• Write — the agent has a remember tool that takes content and a

scope (server | capability) and appends a one-line bullet to the matching file, creating it with a header if absent.

Because the capability store defaults to a path inside this package, the agent writes into it in place. That is committable when the package is installed editable (pip install -e), which is the intended development setup; under a plain wheel install it would write into site-packages instead, so set CAPABILITY_MEMORY_PATH to a writable, tracked location if you deploy that way.

Disable the whole feature with AI_MEMORY_ENABLED=0.

Scripts & recipes

The package bundles server-agnostic tooling split into two layers. They live here (not in any one server repo) because they are reusable capabilities. The aim is a toolbox of small, orthogonal primitives that compose efficiently, plus a few recipes that show how to combine them for common tasks.

Writing one? See CLAUDE.md for the authoring rules (primitive vs. recipe, server-agnostic requirements, shared helpers, quality gates).

Primitives — minecraft_rcon_mcp.scripts

Low-level building blocks, each doing one general thing:

python -m minecraft_rcon_mcp.scripts.rcon "list"
python -m minecraft_rcon_mcp.scripts.count_entities "type=minecraft:cat,distance=..48" --at Steve
python -m minecraft_rcon_mcp.scripts.find_block_entities --x 0 --z 0 --block-id minecraft:chest
python -m minecraft_rcon_mcp.scripts.check_chunk_generated 1216 237 --dimension the_nether
python -m minecraft_rcon_mcp.scripts.find_unexplored_edges 120 45

Recipes — minecraft_rcon_mcp.recipes

Higher-level, task-specific tools composed from the primitives (and sometimes coupled to a particular Minecraft version's mechanics). Each is also a worked example of composition:

python -m minecraft_rcon_mcp.recipes.cat_spawn_check Steve
python -m minecraft_rcon_mcp.recipes.reset_trial_spawners

Configuration

• RCON — read from RCON_HOST / RCON_PORT / RCON_PASSWORD. As a fallback,

rcon.py reads rcon.port / rcon.password from a server.properties in the working directory (or SERVER_PROPERTIES).

• `WORLD_DIR` — tools that read save files need the world folder (the one with

level.dat / dimensions/). This cannot be derived over RCON (no vanilla command exposes the save path), so set WORLD_DIR, or pass --world-dir.

• `--dimension` — region-reading tools default to the overworld; pass

the_nether / the_end / a namespaced id (mymod:custom) for others. Both vanilla (DIM-1/DIM1) and data-driven (dimensions/<ns>/<name>/) layouts resolve automatically.

The world data itself lives in the server deployment, not in this repo — these tools only carry the logic, and reach the world through WORLD_DIR.

Development

This project uses uv for environment and dependency management, Ruff for linting and formatting, and ty for static type checking. The pinned Python version lives in .python-version; uv installs it for you.

uv sync                 # create .venv and install all deps (incl. dev tools)

uv run pytest           # run the test suite
uv run ruff format      # auto-format
uv run ruff check       # lint (add --fix to auto-fix)
uv run ty check         # type-check

License

MIT — see LICENSE.