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

| Variable | Default | Purpose | |---|---|---| | RCON_HOST | localhost | RCON host | | RCON_PORT | 25575 | RCON port | | RCON_PASSWORD | changeme | RCON password (match server.properties) | | LOG_PATH | ./logs/latest.log | Path to the server log to tail. Set this explicitly — the default is relative to the working directory. | | AI_CHAT_ENABLED | 1 | Set 0/false to run a pure RCON tool server (no log tailing, no Anthropic usage). | | AI_PREFIX | ai | Chat trigger prefix (case-insensitive). | | AI_MODEL | claude-sonnet-4-5 | Anthropic model for in-game chat. | | AI_MAX_CONTEXT | 10 | Exchanges retained in the rolling history. | | AI_MAX_TOKENS | 1024 | Max tokens per chat response. | | AI_SYSTEM_PROMPT | (generic built-in) | Replace the entire system prompt. | | AI_SYSTEM_PROMPT_EXTRA | (none) | Append server-specific context (Minecraft version, house rules) to the default prompt. | | AI_MEMORY_ENABLED | 1 | Set 0/false to disable persistent memory (no files read or written). | | SERVER_MEMORY_PATH | ./agent_memory.md | Path to the server-specific memory file (world/player facts). Set this explicitly to a file in your server repo so it is git-tracked there, just like LOG_PATH. | | CAPABILITY_MEMORY_PATH | (packaged agent_memory/capabilities.md) | Path to the server-agnostic capability/script memory. Defaults to a file shipped inside this package; override only if you want it elsewhere. | | WORLD_DIR | — | World save folder (the one with level.dat). Required by the file-reading and structure-building scripts run via run_script (it can't be derived over RCON). | | STRUCTURES_DIR | — | Folder of captured .nbt templates. Lets run_script builders/capture refer to structures by bare name (e.g. generate_monument → ocean_monument). | | MINECRAFT_JAR | (auto: versions//server-.jar) | Server jar read for the vanilla structure catalog/sizing (generate_structure/generate_piece). Set explicitly when the working dir isn't near the jar. | | ANTHROPIC_API_KEY | — | Required for in-game AI chat. |

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:

| Scope | What goes in it | Where it lives | Written via | |---|---|---|---| | server | Facts specific to this server, world, or its players — base/build coordinates, player preferences, house rules, world boundaries, ongoing projects. | The consumer (server) repo, at SERVER_MEMORY_PATH. Committed there. | remember(scope="server") | | capability | Server-agnostic knowledge about this MCP — useful command patterns, what a script does, gotchas, techniques that help on any server. | This package, at CAPABILITY_MEMORY_PATH (defaults to agent_memory/capabilities.md). Committed here. | remember(scope="capability") |

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:

| Primitive | Purpose | Needs world files? | |---|---|---| | rcon | Shared RCON client + CLI for running any command. | No (RCON only) | | count_entities | Run an entity selector and return the parsed count. | No (RCON only) | | find_block_entities | Scan region files for block entities (spawners, chests…). | Yes | | check_chunk_generated | Whether given coords are in generated chunks. | Yes | | find_unexplored_edges | Nearest ungenerated region frontier to a position. | Yes |

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:

| Recipe | Composed from | Notes | |---|---|---| | cat_spawn_check <player> | count_entities | Village cat-spawn gates; thresholds are version-coupled (26.x). | | reset_trial_spawners [player] | find_block_entities + rcon | Finds trial spawners near a player, resets cooldowns. |

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.

minecraft-rcon-mcp