HeadlessMc

HeadlessMc - MCP

MCP サーバーです。HeadlessMc を使って、AI エージェントから Minecraft: Java Edition をインストール、起動、操作できます。

HMC | HMC-Specifics | HMC-Skill

警告

これはプロトタイプです。フィードバックや機能リクエストをお待ちしています。

この MCP サーバーを使うと、Claude Code、Codex、Cursor などの MCP クライアントは次のことができます。

• バニラ版、Fabric、Forge、NeoForge の各バージョン、Java、Modrinth の MOD をインストールできます（HeadlessMc でできることはすべて可能です）。
• 複数のクライアントとサーバーを同時に起動できます。必要に応じてヘッドレス（ディスプレイや GPU なし。CI や Docker など）で実行できます。 各クライアントは、それぞれ独自の MOD、設定、ワールドを持つプロファイル（ゲームディレクトリ）で実行できます。
• 実行中のクライアントを操作できます。画面の読み取り、ボタンのクリック、文字入力、チャット、コマンドの実行、 サーバーへの接続などができます。
• すべてのインスタンスのログを読み取り、サーバーにコンソールコマンドを送信できます。

セットアップ

エージェント	インストール
Claude Code	/plugin install headlessmc-mcp --marketplace headlesshq/headlessmc-mcp
OpenAI Codex	codex plugin marketplace add headlesshq/headlessmc-mcp を実行し、続けて /plugins を開いて、HeadlessMc MCP、Install plugin の順に選択します
GitHub Copilot CLI	copilot plugin marketplace add headlesshq/headlessmc-mcp を実行し、続けて copilot plugin install headlessmc-mcp@headlessmc-mcp を実行します
Cursor	このリポジトリをクローンして plugin を ~/.cursor/plugins/local/headlessmc-mcp にコピーし、Developer: Reload Window を実行します
Gemini CLI	gemini extensions install https://github.com/headlesshq/headlessmc-mcp

HeadlessMc 自体の使い方（インストール方法や、MC-Runtime-Test を使った CI での MOD テストなど）については、 headlessmc-skill もインストールしてください。

ツール

ツール	説明
hmc	HeadlessMc の任意のコマンドラインコマンドを実行します。例：version install fabric 1.21.5、mod search sodium、login。長時間実行されるコマンドは、hmc_job で状態を確認します。
hmc_job	実行中の hmc コマンドの出力とステータスです。
launch_client	クライアントをインストールして起動し（バージョン、ローダーまたはプロファイル、ヘッドレス、オフライン、参加するサーバー、JVM 引数）、メインメニューが表示されるまで待機します。
start_server	Paper/Fabric/Purpur/Forge/NeoForge/vanilla サーバーを作成して起動し、ワールドの読み込みが完了するまで待機します。
list_profiles、create_profile、delete_profile	プロファイルを管理します。プロファイルは、それぞれ独自のゲームディレクトリを持つクライアントのセットアップです。
list_instances	起動済みのクライアントとサーバーを、ステータスとともにすべて一覧表示します。
instance_log	インスタンスの出力の最新行を取得します。正規表現で絞り込むこともできます。
server_command	サーバーにコンソールコマンドを送信し、その出力を返します。
stop_instance	クライアントを終了するか、サーバーを停止します（または強制終了します）。
get_screen	現在の画面を JSON で取得します。ID、テキスト、位置を含むボタンとテキストフィールドが含まれます。
get_state	ゲーム内か、死亡しているか、画面、および位置、体力、ディメンション、サーバー、Ping、TPS、プレイヤー数などの指標を JSON で取得します。
click、set_text、press_key	現在の画面を操作します。click は遷移先の画面を返します。
chat	チャットメッセージまたは /command を送信します。
connect、disconnect	サーバーに参加するか、退出します。
wait_for	in_world、menu、screen:<Name>、log:<regex>、exit のいずれかを待機します。
game_command	ゲーム内で HMC-Specifics の任意のコマンドを実行します（help、metrics、render、respawn、ほかの MOD のコマンド）。

リソーステンプレート：hmc://instances/{id}/log。

複数のクライアントを同時に起動する

実行中の各クライアントには、それぞれ独自のゲームディレクトリが必要です。そうしないと、ファイルが上書きされ、MOD フォルダーが共有されます。 launch_client では、オプションの profile を指定できます。これは、独自のゲームディレクトリを持つ HeadlessMc プロファイル で、存在しない場合は <HeadlessMc data dir>/client/<profile> に作成されます。プロファイルを指定しない場合、クライアントはバージョンのデフォルトのゲームディレクトリを使用します。同じバージョンの別のクライアントがそのディレクトリですでに実行中の場合、MCP サーバーが新しいプロファイル（fabric-1.21.8-2 など）を自動的に作成します。バージョン、ライブラリ、アセットはすべてのプロファイルで共有されます。 エージェントは、セットアップごとにプロファイルを保持し、mod add mod <slug> <profile> でそのプロファイルに MOD を追加できます。

ゲームの制御

ゲーム制御は、HMC-Specifics がサポートするすべての Minecraft バージョンと modloader（1.7.10 から 26.x まで、Forge、Fabric、NeoForge）で動作します。 サーバーは対応する HMC-Specifics の jar をダウンロードし、バージョンに依存しない hmc-mcp-bridge mod とともに、起動前にクライアントの mods フォルダーに配置します。

• ルートプロジェクト（src/）は、Quarkus アプリケーションである MCP サーバーです。headlessmc-web と同様に、HeadlessMc の CDI Bean と picocli コマンドを直接使用します。stdout は MCP チャネルであるため、HeadlessMc のコンソール出力と進捗バーは取得され、代わりにツールの結果として返されます。
• hmc-mcp-bridge は、Minecraft のバージョンに依存しない mod です。HMC-Specifics API を使用し、HMC-Specifics の初期化後にループバックインターフェースで小規模な HTTP サーバーを起動します。MCP サーバーは -Dhmc.mcp.token と -Dhmc.mcp.portFile を使って、ランダムなトークンとポートファイルを渡します。トークンがない場合、mod は何もしません。 コマンド出力はゲームログとは別に返され、JSON コマンドを使用すると、画面と状態が機械可読形式になります。

エージェントは、任意のランチャー（Minecraft Launcher、Prism、MultiMC、IDE の実行構成など）で自分で起動したクライアントも制御できます。mods フォルダーに 2 つの mod を配置してください。

• お使いの Minecraft バージョンと modloader に対応する HMC-Specifics
• リリースの hmc-mcp-bridge。すべてのバージョンと modloader で共通の jar が 1 つあります。

これらの mod が入ったゲームを MCP サーバー経由で起動しなかった場合、bridge はランダムなトークンを生成し、127.0.0.1 の空きポートで待ち受け、ユーザーの状態ディレクトリ（Linux では $XDG_STATE_HOME、それ以外は ~/.local/state、macOS では ~/Library/Application Support、Windows では %LOCALAPPDATA%\state）の headlessmc-mcp/instances/<pid>.json にゲームを登録します。このファイルはユーザー本人だけが読み取れ、ゲームの終了時に削除されます。list_instances はこれらの登録を取得するため、ゲームは 接続済み インスタンスとして表示され、起動したクライアントと同じようにゲームツールを使用できます。ログは logs/latest.log から取得します。MCP サーバーは接続済みのゲームを独自に停止することはなく、これらのゲームには server_command 用のコンソールもありません。bridge を無効にするには、ゲームを -Dhmc.mcp.enabled=false を指定して起動してください。

ユーザーへの確認

エージェントではなくユーザーによる操作が必要な場合があります。MCP クライアントが対応している場合、MCP サーバーは elicitation を使用します。

• Minecraft EULA：start_server は、初めてサーバーを起動する前に、チェックボックスでユーザーに EULA の承認を求めます。elicitation に対応していない場合、エージェントがユーザーに確認し、acceptEula を渡す必要があります。
• Microsoft ログイン：login コマンドは、Microsoft のデバイスコードページを開くようクライアントに求めます（URL モード）。ユーザーはブラウザーでサインインするため、エージェントが認証情報を見ることはありません。
• HeadlessMc コマンドのプロンプトは、フォームとしてユーザーに表示されます。フォームによる elicitation では MCP 仕様で禁止されているため、パスワードやトークンを要求することはありません。
• ファイルを含むプロファイルの削除には、確認を求めます。

時間のかかるインストールや起動では進捗通知が送信され、クライアントでツール呼び出しをキャンセルすると、HeadlessMc コマンドもキャンセルされます。

インストール

GitHub Releases から最新のリリースをダウンロードしてください。

ファイル	プラットフォーム
headlessmc-mcp.jar	Java 25 以降を使用できるすべてのプラットフォーム：java -jar headlessmc-mcp.jar
headlessmc-mcp-windows-x64.exe	Windows x64
headlessmc-mcp-linux-x64, headlessmc-mcp-linux-arm64	Linux（Ubuntu など）x64 および arm64
headlessmc-mcp-macos-arm64, headlessmc-mcp-macos-x64	Apple シリコン搭載 Mac および Intel 搭載 Mac

ビルド

JDK 25 が必要です。

git clone --recurse-submodules https://github.com/headlesshq/headlessmc-mcp.git
cd headlessmc-mcp
./gradlew build
# -> build/headlessmc-mcp-<version>-runner.jar (includes the hmc-mcp-bridge mod)
# -> hmc-mcp-bridge/build/libs/hmc-mcp-bridge-<version>.jar

# native executable for the current platform, needs GraalVM 25 (or add -Dquarkus.native.container-build=true for Linux)
./scripts/build-native.sh
# -> build/headlessmc-mcp-<version>-runner

設定

プロパティ	デフォルト	説明
hmc.mcp.specifics.version	3.0.1	クライアントにインストールする HMC-Specifics のリリースです。
hmc.mcp.specifics.url	GitHub releases	{tag}、{mc}、{loader} を含むダウンロード URL のテンプレートです。
hmc.files.game-for-each-version	true	バージョンごとにゲームディレクトリを分け、mods フォルダーが競合しないようにします。
hmc.mcp.registry	<state dir>/headlessmc-mcp/instances	他のランチャーから起動したゲームの登録先です。ゲームにもこの値を設定してください。

すべての HeadlessMc プロパティ（hmc.*）は、システムプロパティまたは HeadlessMc の設定ファイルでも使用できます。

hmc-mcp-bridge mod は、システムプロパティから hmc.mcp.token、hmc.mcp.portFile、hmc.mcp.host（127.0.0.1）、hmc.mcp.port（0、空いている任意のポート）、hmc.mcp.registry、hmc.mcp.enabled（true）を読み取ります。hmc.mcp.token がない場合、ゲームは接続待ちとして登録されます。

プライバシーと利用規約

MCP サーバーはローカルで実行され、テレメトリーは送信しません。プライバシーポリシーと利用規約をご覧ください。 HeadlessMc - MCP は Minecraft の公式製品ではなく、Mojang または Microsoft による承認や提携を受けていません。