minecraft-paper-mcp

MCP 服务器，用于管理 Paper Minecraft 服务器的后台 — 与 Minecraft 服务器运行在同一台机器上（可直接访问文件并直接操作进程），并通过 RCON 提供游戏内命令。

功能

• 进程控制：server_start、server_stop、server_restart、server_status

• RCON / 游戏内命令：rcon_command（任意原始命令）、players_list、server_tps、server_say、player_kick、player_ban、player_pardon、player_op、player_deop、whitelist_add、whitelist_remove、give_item、teleport_player、set_gamerule、set_weather、set_time

• 读取文件：whitelist_list、ops_list、banned_players_list、banned_ips_list、server_properties_get、server_properties_set（需重启后才生效）

• 日志：logs_tail（查看最近 N 行日志）、logs_search（使用正则表达式 grep）

Related MCP server: Minecraft Server MCP

安装

需要 Node.js 18 或更高版本

cd minecraft-mcp
npm install
npm run build

准备 Paper server

1. 在 Paper 服务器的 server.properties 中启用 RCON：

enable-rcon=true
rcon.port=25575
rcon.password=ใส่รหัสผ่านที่ตั้งเอง_อย่าใช้ค่าว่าง

2. 重要：如果 RCON 端口可能对外暴露，必须用防火墙阻止 — RCON 未加密。如果 MCP 服务器与 Minecraft 服务器运行在同一台机器上，应让 RCON 只监听 127.0.0.1（默认值）。

3. 重启一次 Paper 服务器，使 RCON 配置生效。

设置环境变量

可以参考 .env.example 文件 — 将其复制为 .env 并填入真实值（.env 文件已被加入 .gitignore，不会提交到 GitHub）。MCP 服务器本身不会自动加载 .env（未使用 dotenv）— 请通过 claude_desktop_config.json 中的 env 进行设置，或在实际运行前导出变量。.env 仅供自己记录配置值。

在 Claude Desktop 中设置

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "minecraft-paper": {
      "command": "node",
      "args": ["/absolute/path/to/minecraft-mcp/build/index.js"],
      "env": {
        "MC_SERVER_DIR": "/absolute/path/to/paper-server",
        "MC_START_COMMAND": "java -Xmx6G -Xms2G -jar paper-1.21.jar nogui",
        "MC_RCON_PASSWORD": "รหัสผ่านเดียวกับใน server.properties"
      }
    }
  }
}

然后重启 Claude Desktop

CI

有一个 GitHub Actions workflow（.github/workflows/build.yml），每次向 main 推送或开启 PR 时，都会在 Node 18.x 和 20.x 上运行 npm install + npm run build，以检查项目能否构建通过。如果要用 npm ci 代替 npm install，请先在本地运行一次 npm install 生成 package-lock.json，然后提交该文件到仓库。

备注 / 注意事项

• server_start/server_restart 会以分离（detached）方式生成进程，并将 PID 保存在 MC_PID_FILE 中 — 如果要以正式服务（systemd）的方式运行，也仍然可以使用，但 MCP 本身无法识别 systemd 自行创建的进程。请选择其中一种方式（让这个 MCP 自己负责启动/停止，或让 systemd 管理，只使用依赖 RCON/文件的工具）。

• server_stop 会先尝试通过 RCON 发送 stop 命令（优雅停止），如果无法连接 RCON，则回退为发送 SIGTERM。

• server_properties_set 直接修改文件，需要自行重启服务器后才会生效（不会自动重启）。

• ban/kick/whitelist 命令通过 RCON 执行，不会直接修改 json 文件 — 在服务器运行期间更安全。