MCP 服务器

Minecraft Ops MCP

An MCP server for managing and operating Minecraft servers through multiple backend protocols including MCSManager API, RCON, and MSMP. It provides tools for instance lifecycle management, file operations, console commands, player administration, and server configuration with built-in security controls.

README

Minecraft Ops MCP

一个面向 Minecraft 服务器管理和运维的 MCP stdio 服务。当前版本基于官方 MCP Python SDK 实现，后端适配：

MCSManager API：实例生命周期、日志、文件管理、控制台命令。
RCON：传统控制台命令兜底。
Minecraft Server Management Protocol（MSMP）：Minecraft Java 1.21.9+ 的 JSON-RPC over WebSocket 管理协议。

文档

用户手册：docs/USER_MANUAL.md
开发者框架说明：docs/DEVELOPER_GUIDE.md
当前不足与后续路线：docs/LIMITATIONS.md
集成测试报告：docs/TEST_REPORT_2026-04-14.md
发布检查清单：docs/RELEASE_CHECKLIST.md
安全说明：SECURITY.md
变更日志：CHANGELOG.md

运行方式

推荐在当前 Python 环境中安装项目依赖后运行：

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

开发调试时也可以显式指定 PYTHONPATH：

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

开发与测试

单元测试：

cd /home/damoc/codes/minecraft-ops-mcp
PYTHONPATH=src python3 -B -m unittest discover -s tests

语法检查：

python3 -m compileall -q src scripts

协议级集成探针见 docs/TEST_REPORT_2026-04-14.md 和 docs/RELEASE_CHECKLIST.md。

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",
        "RCON_HOST": "127.0.0.1",
        "RCON_PORT": "25575",
        "RCON_PASSWORD": "replace-me",
        "MSMP_URL": "ws://127.0.0.1:25585",
        "MSMP_SECRET": "replace-me",
        "MINECRAFT_OPS_RAW_COMMAND_ALLOWLIST": "list,time,help",
        "MINECRAFT_OPS_RAW_COMMAND_DENYLIST": "stop,op,deop,ban,ban-ip"
      }
    }
  }
}

也可以参考 .env.example，把变量放进你的 MCP 客户端配置里。这个服务本身不会自动读取 .env 文件，避免让运行时配置来源变得隐式。

主要工具

MCSManager：

server.list_daemons
server.get_daemon_system
server.list_instances
server.get_instance
server.start
server.stop
server.restart
server.kill
server.send_command
server.get_logs
instance.create
instance.update_config
instance.update_config_patch
instance.clone_from_template
instance.delete
instance.reinstall
instance.run_update_task
file.list
file.read
file.download_prepare
file.download_local
file.upload_prepare
file.upload_local
file.upload_url
file.write
file.write_new
file.delete
file.move
file.copy
file.mkdir
file.touch
file.compress
file.uncompress

跨后端便捷工具：

server.save_world：优先 MSMP，其次 RCON，再次 MCSManager。
server.broadcast：优先 MSMP，其次 RCON，再次 MCSManager。

RCON：

rcon.command
rcon.list_players
rcon.time_query
rcon.save_all

MSMP：

msmp.discover
msmp.call
msmp.players.list
msmp.players.kick
msmp.server.status
msmp.server.save
msmp.server.stop
msmp.bans.get
msmp.bans.add
msmp.bans.remove
msmp.bans.set
msmp.bans.clear
msmp.ip_bans.get
msmp.ip_bans.add
msmp.ip_bans.remove
msmp.ip_bans.set
msmp.ip_bans.clear
msmp.allowlist.get
msmp.allowlist.add
msmp.allowlist.remove
msmp.allowlist.set
msmp.allowlist.clear
msmp.operators.get
msmp.operators.add
msmp.operators.remove
msmp.operators.set
msmp.operators.clear
msmp.gamerules.get
msmp.gamerules.update
msmp.server_settings.get
msmp.server_settings.list
msmp.server_settings.set

安全策略

高风险操作需要显式参数：

{ "confirm": true }

如果只是想让 agent 先说明会做什么，传：

{ "dry_run": true }

高风险工具包括实例启停/重启/kill、原始命令、文件写入/删除/移动/压缩/解压/上传、下载到 MCP 本机、踢人、封禁、白名单/OP/游戏规则/服务器设置修改等。所有工具调用会写入审计日志，默认位置：

/tmp/minecraft-ops-mcp-audit.jsonl

可以通过 MINECRAFT_OPS_AUDIT_LOG= 置空来关闭。

原始命令还可以用前缀级 allowlist/denylist 进一步约束：

MINECRAFT_OPS_RAW_COMMAND_ALLOWLIST=list,time,help
MINECRAFT_OPS_RAW_COMMAND_DENYLIST=stop,op,deop,ban,ban-ip

后端建议

实例生命周期、日志和文件管理：优先用 MCSManager API。
玩家、白名单、OP、gamerule、server settings：优先用 MSMP。
老版本服务端或 MSMP 不覆盖的能力：用 RCON 或 MCSManager raw command 兜底。

不要把 RCON、MSMP、MCSManager API key 暴露到公网。MSMP/RCON 最好只监听 localhost、VPN 或隧道；MCSManager 建议使用低权限 API key。

MSMP 参数说明

msmp.call 会按原样传 JSON-RPC params，适合服务端/版本差异较大的新方法：

{
  "method": "minecraft:server/status",
  "read_only": true
}

写操作请使用 confirm=true 或先 dry_run=true。 read_only=true 只会对白名单里的只读 MSMP 方法跳过确认，例如 rpc.discover、minecraft:players、minecraft:server/status、列表查询和 server settings 读取。