minecraft-admin-mcp

minecraft-admin-mcp is a lightweight, self-hosted MCP server that gives an MCP-compatible agent a small set of administration tools for exactly one Minecraft Java Edition server. It uses standard Streamable HTTP and has no dependency on a particular agent or client.

The current release implements the V0.3 scope from PROJECT_SPEC.md (logs, metrics, backups, plus an approval queue for high-risk operations).

Security model

This service is intentionally not a general remote administration interface:

• One MCP process is configured for one Minecraft server; tools never accept a server_id.
• It exposes no shell, code execution, arbitrary RCON, Docker API, or arbitrary filesystem tools.
• RCON operations are fixed adapter methods and all player names and text are validated.
• High-risk operations (restart, ban_player, restore_backup) default to disabled or approval. When set to approval, the Agent only receives request_* tools that enqueue work; approval is never an MCP tool and cannot use the Agent MCP bearer token.
• Operators approve or reject with a separate MC_ADMIN_TOKEN via minecraft-admin-mcp-approve (or the in-process ApprovalAdmin API). The MCP agent token is always rejected for decisions.
• Every write operation, including rejected attempts, is recorded in the instance-local SQLite audit database. Known secret fields are redacted.
• Each instance has its own bearer token and RCON password, read only from environment variables.
• The default container runs as non-root UID 1000 with a read-only root filesystem, all Linux capabilities dropped, and no Docker socket. UID 1000 matches the default owner used by the recommended Minecraft image so private world files remain readable through the read-only mount.

Player names, chat, server output, books, signs, and mod text remain untrusted input. Bearer tokens protect access but do not encrypt traffic; use HTTPS at a reverse proxy, Tailscale, or another trusted private network in production.

Tools

Tool	Operation	Default example permission
get_identity	Describe this one configured server	allow
get_status	Check RCON and online-player status	allow
list_players	List online players	allow
get_whitelist	List whitelisted players	allow
broadcast	Send a validated announcement	allow
whitelist_add	Add a validated player name	allow
whitelist_remove	Remove a validated player name	allow
kick_player	Kick a player with a validated reason	allow
save_world	Run the fixed save-all flush operation	allow
get_metrics	Return reliable visible metrics and null for unavailable values	allow
get_recent_events	Parse recent events from the configured fixed log	allow
get_recent_errors	Parse recent failures from the configured fixed log	allow
create_backup	Create a consistent Zstandard world backup	allow
list_backups	List backup ID, time, size, SHA-256, and reason	allow
request_ban_player	Queue a ban for external approval	approval
request_restart	Queue a controlled restart for external approval	approval
request_restore_backup	Queue a restore by backup id for external approval	approval

When a high-risk permission is allow (typical only on isolated test servers), the direct tools ban_player, restart, and restore_backup are registered instead of the request_* tools.

There is deliberately no raw command tool and no OP grant tool. The Agent tool list never includes approve/reject actions.

High-risk approvals (V0.3)

Agent (MCP token)          Operator (MC_ADMIN_TOKEN)
        │                              │
        │ request_ban_player           │
        ▼                              │
   SQLite approval queue ─────────────►│ minecraft-admin-mcp-approve approve <id>
        │                              │
        │  (no execution yet)          ▼
        │                     fixed RCON ban / stop / restore by id

1. Set high-risk keys to approval (production) or leave them disabled.
2. Set a second secret: MC_ADMIN_TOKEN (≥32 characters, different from MC_MCP_TOKEN).
3. Agent calls request_* and receives a request_id with expiry (default 1 hour).
4. Operator runs:

export MC_ADMIN_TOKEN='...'
uv run minecraft-admin-mcp-approve list
uv run minecraft-admin-mcp-approve approve <request_id> --note "ok"
# or: uv run minecraft-admin-mcp-approve reject <request_id>

Expired requests cannot be executed. A request is executed at most once after approval.

Restart path: fixed RCON stop only. With Compose restart: unless-stopped, the Minecraft container may come back without any Docker socket access from MCP.

Restore path: only an existing instance backup_id (32 hex chars). SHA-256 is verified before extract. Callers cannot supply filesystem paths. The standard Compose stack mounts Minecraft data read-only into MCP; restore execution requires a writable data directory (for example a lab mount). Production operators may still restore on the host after approving the verified request.

Locks: backups and maintenance (restart/restore) are mutually exclusive and return stable error codes (BACKUP_IN_PROGRESS, MAINTENANCE_IN_PROGRESS).

Docker Compose deployment

Requirements: Docker Engine with Compose v2 and enough memory for Minecraft.

cp .env.example .env
# Replace values in .env with independent random secrets (include MC_ADMIN_TOKEN for approvals).
docker compose config
docker compose up -d --build
docker compose ps

The MCP endpoint is http://127.0.0.1:8101/mcp. Minecraft gameplay is published on port 25565. The RCON port has no host mapping; the MCP container reaches it as minecraft:25575 on minecraft_internal.

The default stack mounts:

• minecraft_data at /data in Minecraft and read-only at /minecraft in MCP;
• minecraft_backups at writable /backups only in MCP;
• minecraft_mcp_data at /var/lib/minecraft-admin-mcp for the SQLite audit/approval databases;
• config/survival.example.yaml read-only as the MCP configuration.

Use a copied configuration file for a real deployment instead of editing the example. Host ports can be changed with MC_GAME_PORT and MC_MCP_PORT. Pin the Minecraft image tag and server version according to your own upgrade policy.

Multiple isolated servers

Run a separate Compose project for each Minecraft server. Give each project a different config, host port, project name, bearer token, and RCON password:

docker compose --project-name mc-survival --env-file .env.survival up -d
MC_MCP_PORT=8102 MC_ADMIN_CONFIG_FILE=./config/test.example.yaml \
  docker compose --project-name mc-test --env-file .env.test up -d

Do not attach the stacks to a shared network. Each MCP still uses the internal DNS name minecraft, but Docker project scoping resolves it only inside its own network. Stopping one project does not stop or address another project's services or volumes.

Configuration

Set MC_ADMIN_CONFIG to a YAML file. config/config.example.yaml documents supported fields. Secrets are references, never YAML values:

rcon:
  host: minecraft
  password_env: MC_RCON_PASSWORD
http:
  path: /mcp
  token_env: MC_MCP_TOKEN
approval:
  default_ttl_seconds: 3600
  admin_token_env: MC_ADMIN_TOKEN

Permission values are allow, approval, or disabled:

• allow: register the directly executable tool (for high-risk ops, prefer only on test servers);
• approval: register only request_* for high-risk ops; no direct execute tool; no agent self-approve;
• disabled: do not register the tool.

The bearer token and admin token must each be at least 32 characters. Send the MCP token only in:

Authorization: Bearer <instance-specific-token>

Tokens in URL query parameters are not supported.

Logs, metrics, and backups

The log tools only read minecraft.log_file; callers cannot provide a path. Recognized player chat is returned with trusted: false and source: player_chat. All log-derived content is untrusted, control characters are sanitized, and IP addresses are redacted by default.

The standard Compose deployment does not share the Minecraft PID namespace with MCP. CPU and memory therefore return null instead of reporting the wrong process. Data-volume free space is reported; TPS and MSPT remain null in V0.3.

Backups cover only configured minecraft.world_directories. Creation acquires an instance-wide lock, disables saving, flushes the worlds, writes a .tar.zst archive, calculates SHA-256, writes metadata, restores saving in a finally path, and enforces retention_count. Tool results never expose a filesystem path.

MCP clients

Connection examples are in examples/clients/ for Codex, Claude Desktop, Cursor, Hermes, and a generic MCP client. All use:

• Transport: Streamable HTTP
• URL: https://your-host.example/mcp
• Authentication: Authorization: Bearer ...

Client configuration formats change over time; verify the example against the installed client version. Client-specific behavior is never imported into the MCP server.

Direct development

Python 3.12+ and uv are required.

uv sync --frozen
cp config/survival.example.yaml config/config.yaml
export MC_ADMIN_CONFIG=config/config.yaml
export MC_RCON_PASSWORD='development-rcon-secret'
export MC_MCP_TOKEN='development-token-at-least-32-characters'
export MC_ADMIN_TOKEN='development-admin-token-at-least-32-ch'
uv run minecraft-admin-mcp

Quality gates:

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

Audit and errors

Writes are stored in audit_events with timestamp, server ID, tool, redacted arguments, outcome, stable error code, and duration. Approval decisions are also audited under admin_approve / admin_reject. The service never intentionally stores authorization headers, tokens, or RCON passwords and masks internal exception details at the MCP boundary.

See SECURITY.md for reporting and production guidance and CONTRIBUTING.md for development rules.