Minecraft Ops MCP
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_mcpHTTP 远程访问:
# 旧版 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_TOKENcodex 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-jsonMCP 客户端配置
最小示例:
{
"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 策略约束。
常见流程
健康检查:
server.get_instanceserver.get_logsmsmp.config.get,启用后调用msmp.server.status/msmp.players.listrcon.config.get,需要时调用rcon.list_players/rcon.time_query
启用或修改 RCON:
rcon.config.getrcon.config.set {"dry_run": true, ...}rcon.config.set {"confirm": true, ...}如需加载新配置,重启实例
用
rcon.list_players验证
启用或修改 MSMP:
msmp.config.getmsmp.config.set {"dry_run": true, ...}msmp.config.set {"confirm": true, ...}如需加载新配置,重启实例
用
msmp.discover或msmp.server.status验证
整合包兼容测试:
modpack.snapshot_modlistagent 外部检索候选版本资料
modpack.apply_modlist {"dry_run": true}modpack.apply_modlist {"confirm": true}启动测试服并读日志
modpack.classify_startup_resultmodpack.record_test_run必要时
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。
文档
用户手册:docs/USER_MANUAL.md
开发者手册:docs/DEVELOPER_GUIDE.md
当前不足与路线:docs/LIMITATIONS.md
安全说明:SECURITY.md
变更日志:CHANGELOG.md
建议与 minecraft-ops-runbook skill 配合使用。
Available Tools
71 toolsfile.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 DeleteADestructive
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 ListBRead-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 ReadBRead-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 UncompressADestructive
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 DeleteADestructive
Delete MCSManager instances. Requires confirm=true or dry_run=true.
Inputs: uuids (required), daemonId, deleteFile, confirm, +1 more. Returns: object
instance.reinstallInstance ReinstallADestructive
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 ClearADestructive
Clear the allowlist through MSMP. Requires confirm=true or dry_run=true.
Inputs: confirm, dry_run. Returns: object
msmp.allowlist.getMSMP Allowlist GetCRead-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 ClearADestructive
Clear the player ban list through MSMP. Requires confirm=true or dry_run=true.
Inputs: confirm, dry_run. Returns: object
msmp.bans.getMSMP Bans GetARead-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 DiscoverCRead-onlyIdempotent
Call rpc.discover on the Minecraft Server Management Protocol endpoint.
Inputs: no named parameters. Returns: object
msmp.gamerules.getMSMP Gamerules GetBRead-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 ClearADestructive
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 GetARead-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 ClearADestructive
Clear operators through MSMP. Requires confirm=true or dry_run=true.
Inputs: confirm, dry_run. Returns: object
msmp.operators.getMSMP Operators GetCRead-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 ListARead-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 GetARead-onlyIdempotent
Get one server setting through MSMP, for example difficulty or motd.
Inputs: setting (required). Returns: object
msmp.server_settings.listMSMP Server Settings ListARead-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 StatusCRead-onlyIdempotent
Get server status through MSMP.
Inputs: no named parameters. Returns: object
msmp.server.stopMSMP Server StopADestructive
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 PlayersARead-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 QueryBRead-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 SystemARead-onlyIdempotent
Get MCSManager daemon system status summary.
Inputs: no named parameters. Returns: object
server.get_instanceServer Get InstanceBRead-onlyIdempotent
Get MCSManager instance details.
Inputs: daemonId, uuid. Returns: object
server.get_logsServer Get LogsBRead-onlyIdempotent
Read MCSManager instance output logs.
Inputs: daemonId, uuid, size. Returns: object
server.killServer KillADestructive
Force-kill an MCSManager instance. Requires confirm=true or dry_run=true.
Inputs: daemonId, uuid, confirm, dry_run. Returns: object
server.list_daemonsServer List DaemonsARead-onlyIdempotent
List MCSManager daemon nodes.
Inputs: no named parameters. Returns: object
server.list_instancesServer List InstancesBRead-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 StopADestructive
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
Scored across 71 tools
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.
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.
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.
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
Manage game servers, configurations, players, and groups through the GameServerApp MCP server.
A MCP server built for developers enabling Git based project management with project and personal…
Marketplace and infrastructure for MCP servers and skills: deploy, host, monetize, analytics.
Create, deploy, and operate MCP servers directly from your GitHub repositories.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceAn 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.1MIT
- AlicenseAqualityDmaintenanceAn 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.1912 npm1MIT
- AlicenseNot gradedqualityBmaintenanceA MCP server integrated with the OPanel server management panel, enabling LLM-assisted management of Minecraft servers.16 npm1Mozilla Public 2.0
- AlicenseAqualityNot gradedmaintenanceMCP server for Pterodactyl and Pelican game server panels. 73 tools for server management, power control, file operations, backups, schedules, databases, users, nodes, and eggs.3414 npm-