Skip to main content
Glama

Minecraft Ops MCP

minecraft-ops-mcp 是面向 Minecraft 服务器管理和运维的 MCP 服务,支持 stdio、旧版 HTTP+SSE 和当前 Streamable HTTP。它以 MCSManager 作为主控制面,并提供:

  • 通过 MCSManager 管理实例生命周期、日志、文件、上传和下载;

  • 通过按实例解析的 RCON 执行老版本或命令型运维操作;

  • 通过按实例解析的 MSMP 管理 Minecraft Java 1.21.9+;

  • 为整合包开发提供 jar 元数据、modlist 快照、应用/回滚和测试记录。

当前后端模型

MCP 客户端只配置 MCSManager。RCON 和 MSMP 是实例级配置:

  • RCON 从目标实例的 MCSManager 配置读取:enableRcon、rconIp、rconPort、rconPassword。

  • MSMP 从目标实例的 server.properties 读取:management-server-*。

工具调用通过 daemonId 和 uuid 选择目标实例。同一个 MCP 进程可以管理多个服务器,因为 RCON/MSMP 连接在每次调用时动态解析,而不是从客户端环境变量读取固定 endpoint。

Related MCP server: mcp-cloudron

安装运行

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

默认使用 stdio transport。开发调试:

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

HTTP 远程访问:

# 旧版 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

端点默认值:

  • SSE:GET /sse,客户端随后向 /messages/?session_id=... POST。

  • Streamable HTTP:/mcp。

  • 健康检查:/health。

本地 Codex 注册远程 Streamable HTTP MCP:

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

如果 HTTP MCP 设置了 bearer token,本地 Codex 也需要能读取同名环境变量:

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 只注册客户端配置,不会启动远程服务。HTTP 模式需要在 MCP 所在主机用 systemd、tmux、容器或进程管理器保持服务运行。

HTTP transport 默认启用 Host/Origin 校验。绑定非本机地址时还默认要求 MINECRAFT_OPS_MCP_BEARER_TOKEN,除非显式设置 MINECRAFT_OPS_MCP_ALLOW_UNAUTHENTICATED_HTTP=true。反向代理或公网域名部署时必须设置 --allowed-host 或 MINECRAFT_OPS_MCP_ALLOWED_HOSTS,浏览器客户端还需要设置 --allowed-origin 或 MINECRAFT_OPS_MCP_ALLOWED_ORIGINS。

快速配置 Codex

仓库提供了快速配置脚本,会安装 minecraft-ops-runbook skill,并通过 codex mcp add 注册 MCP server:

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

脚本默认把敏感配置写入 $CODEX_HOME/minecraft-ops-mcp.env,权限为 0600,并生成 $CODEX_HOME/bin/minecraft-ops-mcp-launch 作为 MCP 启动器。Codex config 中只保存启动器路径,不直接保存 API key。

只预览不写入:

scripts/quick_setup.py

生成通用 MCP JSON 片段:

scripts/quick_setup.py --print-json

生成 Streamable HTTP 客户端片段:

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

MCP 客户端配置

最小示例:

{
  "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"
      }
    }
  }
}

生产建议配置安全边界:

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

可选协议默认值:

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

可选 MCP transport 变量:

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

完整变量见 .env.example。

工具分组

  • server.*:实例状态、生命周期、日志、保存、广播、控制台命令。

  • instance.*:创建、更新、patch、克隆、删除、重装、更新任务。

  • file.*:列目录、读写、创建、上传、下载、复制、移动、压缩。

  • rcon.*:RCON 配置读写、安全封装和原始 RCON 命令。

  • msmp.*:MSMP 配置读写、状态、玩家、封禁、白名单、OP、gamerule、server settings、原始 JSON-RPC。

  • modpack.*:jar 检查、modlist 快照、diff、应用/回滚、启动分类、测试记录。

高风险工具需要 dry_run=true 或 confirm=true。原始命令还会受到 allowlist/denylist 策略约束。

常见流程

健康检查:

  1. server.get_instance

  2. server.get_logs

  3. msmp.config.get,启用后调用 msmp.server.status / msmp.players.list

  4. rcon.config.get,需要时调用 rcon.list_players / rcon.time_query

启用或修改 RCON:

  1. rcon.config.get

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

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

  4. 如需加载新配置,重启实例

  5. 用 rcon.list_players 验证

启用或修改 MSMP:

  1. msmp.config.get

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

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

  4. 如需加载新配置,重启实例

  5. 用 msmp.discover 或 msmp.server.status 验证

整合包兼容测试:

  1. modpack.snapshot_modlist

  2. agent 外部检索候选版本资料

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

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

  5. 启动测试服并读日志

  6. modpack.classify_startup_result

  7. modpack.record_test_run

  8. 必要时 modpack.rollback_snapshot

测试

本地检查:

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

真实后端探针需要可丢弃的 MCSManager/Minecraft 测试环境:

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

多服务器探针会创建两个临时实例,验证同一个 MCP 进程可以按 daemonId 和 uuid 动态连接不同的 RCON/MSMP endpoint。

文档

建议与 minecraft-ops-runbook skill 配合使用。

Available Tools

71 tools
file.compressFile CompressA

Create a zip archive in an MCSManager instance. Requires confirm=true or dry_run=true.

Inputs: source (required), targets (required), daemonId, uuid, +2 more. Returns: object

file.copyFile CopyA

Copy files in an MCSManager instance. Requires confirm=true or dry_run=true.

Inputs: targets (required), daemonId, uuid, confirm, +1 more. Returns: object

file.deleteFile DeleteA
Destructive

Delete files or folders from an MCSManager instance. Requires confirm=true or dry_run=true.

Inputs: targets (required), daemonId, uuid, confirm, +1 more. Returns: object

file.download_localFile Download LocalA

Download one MCSManager instance file to the MCP server local filesystem. Requires confirm=true or dry_run=true.

Inputs: file_name (required), daemonId, uuid, local_path, +4 more. Returns: object

file.download_prepareFile Download PrepareA

Create a temporary MCSManager daemon download token for one instance file.

Inputs: file_name (required), daemonId, uuid. Returns: object

file.listFile ListB
Read-onlyIdempotent

List files in an MCSManager instance directory.

Inputs: daemonId, uuid, target, page, +1 more. Returns: object

file.mkdirFile MkdirB

Create a folder in an MCSManager instance.

Inputs: target (required), daemonId, uuid. Returns: object

file.moveFile MoveA

Move or rename files in an MCSManager instance. Requires confirm=true or dry_run=true.

Inputs: targets (required), daemonId, uuid, confirm, +1 more. Returns: object

file.readFile ReadB
Read-onlyIdempotent

Read a text file from an MCSManager instance.

Inputs: target (required), daemonId, uuid. Returns: object

file.touchFile TouchB

Create an empty file in an MCSManager instance.

Inputs: target (required), daemonId, uuid. Returns: object

file.uncompressFile UncompressA
Destructive

Extract a zip archive in an MCSManager instance. Requires confirm=true or dry_run=true.

Inputs: source (required), target (required), daemonId, uuid, +3 more. Returns: object

file.upload_localFile Upload LocalA

Upload a local file into an MCSManager instance directory. Requires confirm=true or dry_run=true.

Inputs: upload_dir (required), local_path (required), daemonId, uuid, +4 more. Returns: object

file.upload_prepareFile Upload PrepareB

Create a temporary MCSManager daemon upload token for one instance directory.

Inputs: upload_dir (required), daemonId, uuid. Returns: object

file.upload_urlFile Upload UrlA

Download a remote URL on the MCP server and upload it into an MCSManager instance. Requires confirm=true or dry_run=true.

Inputs: url (required), upload_dir (required), daemonId, uuid, +5 more. Returns: object

file.writeFile WriteA

Write a text file in an MCSManager instance. Requires confirm=true or dry_run=true.

Inputs: target (required), text (required), daemonId, uuid, +2 more. Returns: object

file.write_newFile Write NewA

Create a text file with touch -> write, optionally refusing to overwrite existing files. Requires confirm=true or dry_run=true.

Inputs: target (required), text (required), daemonId, uuid, +3 more. Returns: object

instance.clone_from_templateInstance Clone From TemplateA

Create a new MCSManager instance from an existing instance config. Requires confirm=true or dry_run=true.

Inputs: source_uuid (required), source_daemonId, daemonId, nickname, +4 more. Returns: object

instance.createInstance CreateA

Create an MCSManager instance. Requires confirm=true or dry_run=true.

Inputs: config (required), daemonId, confirm, dry_run. Returns: object

instance.deleteInstance DeleteA
Destructive

Delete MCSManager instances. Requires confirm=true or dry_run=true.

Inputs: uuids (required), daemonId, deleteFile, confirm, +1 more. Returns: object

instance.reinstallInstance ReinstallA
Destructive

Reinstall an MCSManager instance from a package URL. Requires confirm=true or dry_run=true.

Inputs: targetUrl (required), title (required), daemonId, uuid, +3 more. Returns: object

instance.run_update_taskInstance Run Update TaskA

Run the configured MCSManager update task. Requires confirm=true or dry_run=true.

Inputs: daemonId, uuid, confirm, dry_run. Returns: object

instance.update_configInstance Update ConfigA

Update an MCSManager instance config. Requires confirm=true or dry_run=true.

Inputs: config (required), daemonId, uuid, confirm, +1 more. Returns: object

instance.update_config_patchInstance Update Config PatchA

Read the current MCSManager instance config, deep-merge a patch, and update it. Requires confirm=true or dry_run=true.

Inputs: patch (required), daemonId, uuid, confirm, +1 more. Returns: object

msmp.allowlist.addMSMP Allowlist AddA

Add players to the allowlist through MSMP. Requires confirm=true or dry_run=true.

Inputs: players (required), confirm, dry_run. Returns: object

msmp.allowlist.clearMSMP Allowlist ClearA
Destructive

Clear the allowlist through MSMP. Requires confirm=true or dry_run=true.

Inputs: confirm, dry_run. Returns: object

msmp.allowlist.getMSMP Allowlist GetC
Read-onlyIdempotent

Get the allowlist through MSMP.

Inputs: no named parameters. Returns: object

msmp.allowlist.removeMSMP Allowlist RemoveA

Remove players from the allowlist through MSMP. Requires confirm=true or dry_run=true.

Inputs: players (required), confirm, dry_run. Returns: object

msmp.allowlist.setMSMP Allowlist SetA

Replace the allowlist through MSMP. Requires confirm=true or dry_run=true.

Inputs: players (required), confirm, dry_run. Returns: object

msmp.bans.addMSMP Bans AddA

Add player bans through MSMP. Requires confirm=true or dry_run=true.

Inputs: players (required), reason, source, expires, +2 more. Returns: object

msmp.bans.clearMSMP Bans ClearA
Destructive

Clear the player ban list through MSMP. Requires confirm=true or dry_run=true.

Inputs: confirm, dry_run. Returns: object

msmp.bans.getMSMP Bans GetA
Read-onlyIdempotent

Get the player ban list through MSMP.

Inputs: no named parameters. Returns: object

msmp.bans.removeMSMP Bans RemoveA

Remove player bans through MSMP. Requires confirm=true or dry_run=true.

Inputs: players (required), confirm, dry_run. Returns: object

msmp.bans.setMSMP Bans SetA

Replace the player ban list through MSMP. Requires confirm=true or dry_run=true.

Inputs: players (required), reason, source, expires, +2 more. Returns: object

msmp.callMSMP CallA

Call an arbitrary MSMP JSON-RPC method. Set read_only=true for safe reads; otherwise confirm=true is required.

Inputs: method (required), params, read_only, confirm, +1 more. Returns: object

msmp.discoverMSMP DiscoverC
Read-onlyIdempotent

Call rpc.discover on the Minecraft Server Management Protocol endpoint.

Inputs: no named parameters. Returns: object

msmp.gamerules.getMSMP Gamerules GetB
Read-onlyIdempotent

Get game rules through MSMP.

Inputs: no named parameters. Returns: object

msmp.gamerules.updateMSMP Gamerules UpdateA

Update a game rule through MSMP. Requires confirm=true or dry_run=true.

Inputs: rule (required), value (required), confirm, dry_run. Returns: object

msmp.ip_bans.addMSMP Ip Bans AddA

Add IP bans through MSMP. Requires confirm=true or dry_run=true.

Inputs: ips (required), reason, source, expires, +2 more. Returns: object

msmp.ip_bans.clearMSMP Ip Bans ClearA
Destructive

Clear the IP ban list through MSMP. Requires confirm=true or dry_run=true.

Inputs: confirm, dry_run. Returns: object

msmp.ip_bans.getMSMP Ip Bans GetA
Read-onlyIdempotent

Get the IP ban list through MSMP.

Inputs: no named parameters. Returns: object

msmp.ip_bans.removeMSMP Ip Bans RemoveA

Remove IP bans through MSMP. Requires confirm=true or dry_run=true.

Inputs: ips (required), confirm, dry_run. Returns: object

msmp.ip_bans.setMSMP Ip Bans SetA

Replace the IP ban list through MSMP. Requires confirm=true or dry_run=true.

Inputs: ips (required), reason, source, expires, +2 more. Returns: object

msmp.operators.addMSMP Operators AddA

Add operators through MSMP. Requires confirm=true or dry_run=true.

Inputs: players (required), permission_level, bypasses_player_limit, confirm, +1 more. Returns: object

msmp.operators.clearMSMP Operators ClearA
Destructive

Clear operators through MSMP. Requires confirm=true or dry_run=true.

Inputs: confirm, dry_run. Returns: object

msmp.operators.getMSMP Operators GetC
Read-onlyIdempotent

Get operators through MSMP.

Inputs: no named parameters. Returns: object

msmp.operators.removeMSMP Operators RemoveA

Remove operators through MSMP. Requires confirm=true or dry_run=true.

Inputs: players (required), confirm, dry_run. Returns: object

msmp.operators.setMSMP Operators SetA

Replace the operator list through MSMP. Requires confirm=true or dry_run=true.

Inputs: players (required), permission_level, bypasses_player_limit, confirm, +1 more. Returns: object

msmp.players.kickMSMP Players KickA

Kick one or more players through MSMP. Requires confirm=true or dry_run=true.

Inputs: players (required), message, confirm, dry_run. Returns: object

msmp.players.listMSMP Players ListA
Read-onlyIdempotent

List connected players through MSMP.

Inputs: no named parameters. Returns: object

msmp.server.saveMSMP Server SaveA

Save server state through MSMP. Requires confirm=true or dry_run=true.

Inputs: flush, confirm, dry_run. Returns: object

msmp.server_settings.getMSMP Server Settings GetA
Read-onlyIdempotent

Get one server setting through MSMP, for example difficulty or motd.

Inputs: setting (required). Returns: object

msmp.server_settings.listMSMP Server Settings ListA
Read-onlyIdempotent

Discover readable and writable MSMP server settings from rpc.discover.

Inputs: no named parameters. Returns: object

msmp.server_settings.setMSMP Server Settings SetA

Set one server setting through MSMP. Requires confirm=true or dry_run=true.

Inputs: setting (required), value (required), confirm, dry_run. Returns: object

msmp.server.statusMSMP Server StatusC
Read-onlyIdempotent

Get server status through MSMP.

Inputs: no named parameters. Returns: object

msmp.server.stopMSMP Server StopA
Destructive

Stop server through MSMP. Requires confirm=true or dry_run=true.

Inputs: confirm, dry_run. Returns: object

rcon.commandRCON CommandA

Send a raw RCON command. Requires confirm=true or dry_run=true.

Inputs: command (required), confirm, dry_run. Returns: object

rcon.list_playersRCON List PlayersA
Read-onlyIdempotent

List online players through RCON using the fixed list command.

Inputs: no named parameters. Returns: object

rcon.save_allRCON Save AllB

Save the world through RCON using save-all or save-all flush.

Inputs: flush. Returns: object

rcon.time_queryRCON Time QueryB
Read-onlyIdempotent

Query server time through RCON using time query daytime/gametime/day.

Inputs: query. Returns: object

server.broadcastServer BroadcastA

Broadcast a system chat message using MSMP, RCON, or MCSManager.

Inputs: message (required), backend, targets, overlay, +2 more. Returns: object

server.get_daemon_systemServer Get Daemon SystemA
Read-onlyIdempotent

Get MCSManager daemon system status summary.

Inputs: no named parameters. Returns: object

server.get_instanceServer Get InstanceB
Read-onlyIdempotent

Get MCSManager instance details.

Inputs: daemonId, uuid. Returns: object

server.get_logsServer Get LogsB
Read-onlyIdempotent

Read MCSManager instance output logs.

Inputs: daemonId, uuid, size. Returns: object

server.killServer KillA
Destructive

Force-kill an MCSManager instance. Requires confirm=true or dry_run=true.

Inputs: daemonId, uuid, confirm, dry_run. Returns: object

server.list_daemonsServer List DaemonsA
Read-onlyIdempotent

List MCSManager daemon nodes.

Inputs: no named parameters. Returns: object

server.list_instancesServer List InstancesB
Read-onlyIdempotent

List instances on an MCSManager daemon.

Inputs: daemonId, page, page_size, instance_name, +1 more. Returns: object

server.restartServer RestartA

Restart an MCSManager instance. Requires confirm=true or dry_run=true.

Inputs: daemonId, uuid, confirm, dry_run. Returns: object

server.save_worldServer Save WorldB

Save the Minecraft world using MSMP, RCON, or MCSManager.

Inputs: backend, daemonId, uuid, flush. Returns: object

server.send_commandServer Send CommandA

Send a raw console command through MCSManager. Requires confirm=true or dry_run=true.

Inputs: command (required), daemonId, uuid, confirm, +1 more. Returns: object

server.startServer StartA

Start an MCSManager instance. Requires confirm=true or dry_run=true.

Inputs: daemonId, uuid, confirm, dry_run. Returns: object

server.stopServer StopA
Destructive

Stop an MCSManager instance. Requires confirm=true or dry_run=true.

Inputs: daemonId, uuid, confirm, dry_run. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 71 tools

    Disambiguation4/5

    The tools are well-organized into clear categories (file, instance, msmp, rcon, server) with distinct purposes within each category. However, there is some potential for confusion between similar operations like server.save_world and rcon.save_all, or between different save methods. Overall, the hierarchical naming helps agents distinguish between tools effectively.

    Naming Consistency5/5

    The tool names follow an extremely consistent pattern of category.verb_noun throughout (e.g., file.list, msmp.allowlist.get, server.start). All tools use snake_case with clear hierarchical organization, making the naming scheme predictable and easy to understand.

    Tool Count2/5

    With 71 tools, this server has far too many tools for effective agent use. While the domain (Minecraft server management) is complex, the tool count creates overwhelming complexity and redundancy (e.g., multiple ways to save worlds, multiple player listing methods). A more streamlined set would be more appropriate.

    Completeness5/5

    The tool surface provides comprehensive coverage of Minecraft server management operations. It includes complete CRUD for files, instances, player management (allowlist, bans, operators), server control (start/stop/restart), configuration management, and multiple communication protocols (MSMP, RCON, MCSManager). No obvious gaps exist for the stated purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      An MCP server that enables programmatic management and monitoring of development servers through a unified interface and interactive TUI. It provides tools for process control, log streaming, and experimental browser automation via Playwright.
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server for managing Cloudron instances that enables monitoring and controlling self-hosted applications, backups, and infrastructure. It provides tools for listing installed apps, retrieving system status, and performing administrative tasks through the Model Context Protocol.
      19
      12 npm
      1
      MIT
    • A
      license
      A
      quality
      Not graded
      maintenance
      MCP server for Pterodactyl and Pelican game server panels. 73 tools for server management, power control, file operations, backups, schedules, databases, users, nodes, and eggs.
      34
      14 npm
      -