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.
• get_ai_chat_status tool — report listener health, history size, model, and log path.

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.
ANTHROPIC_API_KEY	—	Required for in-game AI chat.

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.