minecraft-paper-mcp

MCP server for managing a Paper Minecraft server backend — runs on the same machine as the Minecraft server (direct file access and process control) alongside in-game commands via RCON

Features

• Process control: server_start, server_stop, server_restart, server_status

• RCON / in-game commands: rcon_command (any raw 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

• File reading: whitelist_list, ops_list, banned_players_list, banned_ips_list, server_properties_get, server_properties_set (requires restart to take effect)

• Logs: logs_tail (view the last N log lines), logs_search (grep with regex)

Related MCP server: Minecraft Server MCP

Installation

Requires Node.js 18 or higher

cd minecraft-mcp
npm install
npm run build

Preparing the Paper server

1. Enable RCON in the Paper server's server.properties:

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

2. Important: If the RCON port is exposed externally, you must block it with a firewall — RCON is not encrypted. It should only listen on 127.0.0.1 (the default) if the MCP server runs on the same machine.

3. Restart the Paper server once for the RCON settings to take effect.

Setting up environment variables

There is a .env.example file for reference — copy it to .env and fill in the real values (the .env file is already in .gitignore and will not be committed to GitHub). The MCP server itself does not load .env automatically (it does not use dotenv) — set values via env in claude_desktop_config.json or export the variables before actually running. .env is only for keeping notes for yourself.

Setting up in Claude Desktop

Add to 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"
      }
    }
  }
}

Then restart Claude Desktop

CI

There is a GitHub Actions workflow (.github/workflows/build.yml) that runs npm install + npm run build on Node 18.x and 20.x on every push or PR into main to verify the project builds. If you want to use npm ci instead of npm install, run npm install once on your own machine to generate package-lock.json, then commit that file to the repo first.

Notes / Cautions

• server_start/server_restart spawn a detached process and store the PID in MC_PID_FILE — if you want to run it as a real service (systemd), it still works, but the MCP will not recognize processes that systemd creates itself. Choose one approach (let this MCP start/stop it itself, or let systemd manage it and only use tools that rely on RCON/files).

• server_stop will try to send the stop command via RCON first (graceful). If RCON cannot be reached, it falls back to SIGTERM.

• server_properties_set edits the file directly — you must restart the server yourself for it to take effect (no auto-restart).

• ban/kick/whitelist commands are done via RCON, not by editing the json files directly — safer while the server is running.