minecraft-paper-mcp

Paper Minecraftサーバーのバックエンドを管理するMCPサーバー — 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 (regexでgrep)

Related MCP server: Minecraft Server MCP

インストール

Node.js 18 以上が必要です

cd minecraft-mcp
npm install
npm run build

Paperサーバーの準備

1. Paperサーバーの server.properties でRCONを有効にします:

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

2. 重要: RCONポートが外部に公開されている場合は、ファイアウォールで遮断してください — RCONは暗号化されていません。 MCPサーバーが同じマシンで動作する場合は、127.0.0.1（デフォルト）のみにバインドするべきです。

3. RCON設定を反映するため、Paperサーバーを一度再起動します。

環境変数の設定

参考用に .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ワークフロー（.github/workflows/build.yml）があり、main へのpushまたはPR作成のたびに Node 18.x と 20.x で npm install + npm run build を実行し、プロジェクトがビルドできることを確認します。 npm install の代わりに npm ci を使いたい場合は、自分のマシンで一度 npm install を実行して package-lock.json を生成し、そのファイルを事前にリポジトリへコミットしてください。

注記 / 注意事項

• server_start/server_restart はdetachedプロセスとしてspawnし、PIDを MC_PID_FILE に保存します — 本格的なサービス（systemd）として実行する場合も使用できますが、MCPはsystemdが作成したプロセスを認識しません。 どちらかの方法を選択してください（このMCPにstart/stopを任せるか、systemdで管理してRCON/ファイルに依存するツールのみを使用するか）

• server_stop はまずRCON経由で stop コマンドを送信します（グレースフル）。RCONに接続できない場合は SIGTERM にフォールバックします

• server_properties_set はファイルを直接編集します。反映にはサーバーを自分で再起動する必要があります（自動再起動はしません）

• ban/kick/whitelistコマンドはRCON経由で実行され、JSONファイルを直接編集しません — サーバー実行中はより安全です