Minecraft Ops MCP

minecraft-ops-mcp is an MCP service for Minecraft server management and operations, supporting stdio, legacy HTTP+SSE, and current Streamable HTTP. It uses MCSManager as the primary control plane and provides:

• Instance lifecycle management, logs, files, uploads, and downloads via MCSManager;

• Legacy or command-based operational tasks via per-instance RCON parsing;

• Minecraft Java 1.21.9+ management via per-instance MSMP parsing;

• Jar metadata, modlist snapshots, apply/rollback, and test logging for modpack development.

Current Backend Model

MCP clients only configure MCSManager. RCON and MSMP are instance-level configurations:

• RCON is read from the target instance's MCSManager configuration: enableRcon, rconIp, rconPort, rconPassword.

• MSMP is read from the target instance's server.properties: management-server-*.

Tool calls select the target instance via daemonId and uuid. A single MCP process can manage multiple servers because RCON/MSMP connections are dynamically resolved at each call, rather than reading fixed endpoints from client environment variables.

Related MCP server: mcp-cloudron

Installation and Execution

cd /home/damoc/codes/minecraft-ops-mcp
python3 -m pip install -e .
minecraft-ops-mcp

Default uses stdio transport. For development and debugging:

cd /home/damoc/codes/minecraft-ops-mcp
PYTHONPATH=src python3 -m minecraft_ops_mcp

HTTP remote access:

# 旧版 HTTP+SSE transport，兼容 MCP 2024-11-05 客户端
MINECRAFT_OPS_MCP_BEARER_TOKEN=replace-with-long-random-token \
PYTHONPATH=src python3 -m minecraft_ops_mcp \
  --transport sse \
  --host 0.0.0.0 \
  --port 8000 \
  --allowed-host mcsm-host.example:8000

# 当前 MCP 标准推荐的 Streamable HTTP transport，适合支持 --url 的客户端
MINECRAFT_OPS_MCP_BEARER_TOKEN=replace-with-long-random-token \
PYTHONPATH=src python3 -m minecraft_ops_mcp \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 8000 \
  --allowed-host mcsm-host.example:8000

Endpoint defaults:

• SSE: GET /sse, client then POSTs to /messages/?session_id=....

• Streamable HTTP: /mcp.

• Health check: /health.

Register remote Streamable HTTP MCP in local Codex:

codex mcp add minecraft-ops --url http://mcsm-host.example:8000/mcp

If the HTTP MCP has a bearer token set, the local Codex also needs to be able to read the environment variable of the same name:

export MINECRAFT_OPS_MCP_BEARER_TOKEN=replace-with-long-random-token
codex mcp add minecraft-ops --url http://mcsm-host.example:8000/mcp --bearer-token-env-var MINECRAFT_OPS_MCP_BEARER_TOKEN

codex mcp add --url only registers the client configuration and does not start the remote service. HTTP mode requires keeping the service running on the host where the MCP resides using systemd, tmux, a container, or a process manager.

HTTP transport enables Host/Origin validation by default. Binding to non-local addresses also requires MINECRAFT_OPS_MCP_BEARER_TOKEN by default, unless MINECRAFT_OPS_MCP_ALLOW_UNAUTHENTICATED_HTTP=true is explicitly set. When deploying with a reverse proxy or public domain, --allowed-host or MINECRAFT_OPS_MCP_ALLOWED_HOSTS must be set; browser clients also require --allowed-origin or MINECRAFT_OPS_MCP_ALLOWED_ORIGINS.

Quick Codex Configuration

The repository provides a quick configuration script that installs the minecraft-ops-runbook skill and registers the MCP server via codex mcp add:

cd /home/damoc/codes/minecraft-ops-mcp
MCSM_BASE_URL=http://your-mcsm-host:23333 \
MCSM_API_KEY=replace-me \
MCSM_DEFAULT_DAEMON_ID=replace-me \
MCSM_DEFAULT_INSTANCE_UUID=replace-me \
scripts/quick_setup.py --write --replace

By default, the script writes sensitive configurations to $CODEX_HOME/minecraft-ops-mcp.env with 0600 permissions and generates $CODEX_HOME/bin/minecraft-ops-mcp-launch as the MCP launcher. The Codex config only saves the launcher path and does not directly save the API key.

Preview without writing:

scripts/quick_setup.py

Generate generic MCP JSON snippet:

scripts/quick_setup.py --print-json

Generate Streamable HTTP client snippet:

scripts/quick_setup.py --mcp-transport streamable-http --print-json

MCP Client Configuration

Minimal example:

{
  "mcpServers": {
    "minecraft-ops": {
      "command": "python3",
      "args": ["-m", "minecraft_ops_mcp"],
      "cwd": "/home/damoc/codes/minecraft-ops-mcp",
      "env": {
        "PYTHONPATH": "src",
        "MCSM_BASE_URL": "http://127.0.0.1:23333",
        "MCSM_API_KEY": "replace-me",
        "MCSM_DEFAULT_DAEMON_ID": "replace-me",
        "MCSM_DEFAULT_INSTANCE_UUID": "replace-me",
        "MINECRAFT_OPS_AUDIT_LOG": "/tmp/minecraft-ops-mcp-audit.jsonl"
      }
    }
  }
}

Production recommended configuration for security boundaries:

MINECRAFT_OPS_RAW_COMMAND_ALLOWLIST=list,time,help
MINECRAFT_OPS_RAW_COMMAND_DENYLIST=stop,op,deop,ban,ban-ip
MINECRAFT_OPS_MAX_BYTES=268435456
MINECRAFT_OPS_UPLOAD_ALLOWED_DIRS=/tmp/minecraft-ops-mcp-downloads,/srv/minecraft-staging
MINECRAFT_OPS_FILE_OPERATION_WHITELIST=server.properties,config,mods,logs,crash-reports
MINECRAFT_OPS_UPLOAD_URL_ALLOWED_DOMAINS=example.com,cdn.example.com
MINECRAFT_OPS_MODPACK_WORKSPACE=/srv/minecraft-ops/modpack-workspace

Optional protocol defaults:

MINECRAFT_OPS_RCON_TIMEOUT_SECONDS=5
MINECRAFT_OPS_RCON_ENCODING=utf-8
MINECRAFT_OPS_MSMP_TIMEOUT_SECONDS=8
MINECRAFT_OPS_MSMP_TLS_VERIFY=true

Optional MCP transport variables:

MINECRAFT_OPS_MCP_TRANSPORT=stdio
MINECRAFT_OPS_MCP_HOST=127.0.0.1
MINECRAFT_OPS_MCP_PORT=8000
MINECRAFT_OPS_MCP_ALLOWED_HOSTS=mcsm-host.example:8000
MINECRAFT_OPS_MCP_ALLOWED_ORIGINS=https://agent.example
MINECRAFT_OPS_MCP_BEARER_TOKEN=replace-with-long-random-token

See .env.example for full variables.

Tool Grouping

• server.*: Instance status, lifecycle, logs, save, broadcast, console commands.

• instance.*: Create, update, patch, clone, delete, reinstall, update tasks.

• file.*: List directory, read/write, create, upload, download, copy, move, compress.

• rcon.*: RCON configuration read/write, security wrapping, and raw RCON commands.

• msmp.*: MSMP configuration read/write, status, players, bans, whitelist, OP, gamerule, server settings, raw JSON-RPC.

• modpack.*: Jar check, modlist snapshot, diff, apply/rollback, startup classification, test records.

High-risk tools require dry_run=true or confirm=true. Raw commands are also subject to allowlist/denylist policies.

Common Workflows

Health check:

1. server.get_instance

2. server.get_logs

3. msmp.config.get, call msmp.server.status / msmp.players.list after enabling

4. rcon.config.get, call rcon.list_players / rcon.time_query when needed

Enable or modify RCON:

1. rcon.config.get

2. rcon.config.set {"dry_run": true, ...}

3. rcon.config.set {"confirm": true, ...}

4. Restart instance if new configuration needs to be loaded

5. Verify with rcon.list_players

Enable or modify MSMP:

1. msmp.config.get

2. msmp.config.set {"dry_run": true, ...}

3. msmp.config.set {"confirm": true, ...}

4. Restart instance if new configuration needs to be loaded

5. Verify with msmp.discover or msmp.server.status

Modpack compatibility testing:

1. modpack.snapshot_modlist

2. Agent retrieves candidate version information externally

3. modpack.apply_modlist {"dry_run": true}

4. modpack.apply_modlist {"confirm": true}

5. Start test server and read logs

6. modpack.classify_startup_result

7. modpack.record_test_run

8. modpack.rollback_snapshot if necessary

Testing

Local check:

PYTHONPATH=src python3 -B -m unittest discover -s tests
python3 -m compileall -q src scripts

Real backend probes require disposable MCSManager/Minecraft test environments:

python3 -B scripts/mcp_integration_probe.py > /tmp/minecraft-ops-mcp-probe-report.json
python3 -B scripts/msmp_temp_instance_probe.py > /tmp/minecraft-ops-mcp-msmp-probe-report.json
python3 -B scripts/multi_server_backend_probe.py > /tmp/minecraft-ops-mcp-multi-probe-report.json

Multi-server probes create two temporary instances to verify that the same MCP process can dynamically connect to different RCON/MSMP endpoints based on daemonId and uuid.

Documentation

• User Manual: docs/USER_MANUAL.md

• Developer Guide: docs/DEVELOPER_GUIDE.md

• Current Limitations and Roadmap: docs/LIMITATIONS.md

• Test Report: docs/TEST_REPORT_2026-04-14.md

• Release Checklist: docs/RELEASE_CHECKLIST.md

• Security Notice: SECURITY.md

• Changelog: CHANGELOG.md

Recommended for use with the minecraft-ops-runbook skill.