FiveM MCP

fivem-mcp

AI エージェント（Claude、Qwen、その他 MCP に対応するもの）が、同じマシンから FiveM サーバーの構築、実行、ライブテストを行える MCP（Model Context Protocol）サーバーです。

「ゲーム内で実際に動いたのか？」という疑問に答えるための、足りなかったテストレイヤーです。エージェントは実際のコンソールコマンドを実行し、サーバーログと、起動中の FiveM クライアントのライブ F8 コンソールの両方を監視し、特定の出力を待ってから反応できます。キーボードを操作する必要はありません。

agent (Claude / Qwen / …)
   │  MCP over stdio
   ▼
fivem-mcp-server ──► UDP RCON / getinfo ──► FXServer (game port, e.g. 30120)
                   ──► TCP devcon (29200/29300) ──► FiveM Legacy client F8 console
                   ──► tail ─────────────────────► FXServer's redirected stdout log

ステータス

v0.5 では、一連の作業全体に対応しています。サーバーコンソール（RCON）、クライアント F8 コンソール（devcon）、ゲームウィンドウ（起動、フォーカス、スクリーンショット、キーボード／マウス）、ネイティブ、エクスポート、NUI コールバック用のゲーム内ブリッジ（mcpb）、さらにすぐに使えるテスト用プロンプトを利用できます。ツールは構造化コンテンツを返し、MCP アノテーションを含み、クライアントがキャンセルするとすぐに停止します。これらはすべて、実際の FXServer と FiveM Legacy クライアントでライブ検証済みです（docs/plan.md および scripts/live-*.mjs を参照）。

公開先

チャネル	アドレス
npm	fivem-mcp-server — npx -y fivem-mcp-server
MCP Registry	io.github.ziyacivan/fivem-mcp（registry.modelcontextprotocol.io）
ソースリリース	GitHub Releases、vX.Y.Z タグ付き

このリポジトリの GitHub Packages サイドバーは意図的に空にしています。成果物は GitHub Packages ではなく npmjs.com にあります。GitHub Packages を使うと、スコープ付きの @ziyacivan/ パッケージ名と、メリットのない 2 つ目のレジストリが必要になるためです。

要件

• Node 22 以降（サーバー側は Windows、macOS、Linux に対応。クライアントの devcon は FiveM クライアントが動作する環境で利用できます。devcon はデフォルトで localhost にバインドするため、client_* ツールを使う場合、このツールはクライアントと同じマシンで実行する必要があります）。
• 管理権限のある起動中の FXServer（server_command には rcon_password の設定が必要です）。
• クライアントコンソール用ツールには Legacy FiveM クライアントが必要です（Enhanced ではクライアントの devcon ポートが削除されました。docs/protocol.md を参照してください）。
• キーボード／マウス／スクリーンショット用ツールは Windows 専用で、ゲームが動作するマシンで実行してください。それ以外のプラットフォームでは、これらを除くすべてのツールが通常どおり提供されます。

インストール

npm で公開されているため、クローンは不要です。1 行で Claude Code に追加できます。

claude mcp add fivem -s user \
  -e FIVEM_RCON_PASSWORD=your-rcon-password \
  -e FIVEM_SERVER_LOG=C:\FXServer\my-data\server.log \
  -- npx -y fivem-mcp-server

（-s user を指定すると、すべてのプロジェクトで利用できます。プロジェクト単位の設定にするには省略してください。claude mcp get fivem で確認すると、ステータスが ✓ Connected と表示されます。削除するには claude mcp remove fivem -s user を実行します。）

プロジェクトで共有する設定には、リポジトリのルートに .mcp.json を置いてコミットします。初回の起動時に Claude Code が承認を求めます。また、環境変数の値は ${VAR} 展開を使って、ローカルの .env がないシェルから補間できます。

{
  "mcpServers": {
    "fivem": {
      "command": "npx",
      "args": ["-y", "fivem-mcp-server"],
      "env": {
        "FIVEM_RCON_PASSWORD": "${FIVEM_RCON_PASSWORD}",
        "FIVEM_SERVER_LOG": "${FIVEM_SERVER_LOG}"
      }
    }
  }
}

Claude Desktop（または JSON 設定に対応するクライアント）の場合は、claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "fivem": {
      "command": "npx",
      "args": ["-y", "fivem-mcp-server"],
      "env": { "FIVEM_RCON_PASSWORD": "your-rcon-password" }
    }
  }
}

このサーバーは MCP Registry に io.github.ziyacivan/fivem-mcp としても登録されています。ソースからビルドする場合（開発用）：

git clone https://github.com/ziyacivan/fivem-mcp
cd fivem-mcp && pnpm install && pnpm build
claude mcp add fivem -- node ./dist/index.js        # points at your working copy

設定（環境変数）

変数	デフォルト	説明
FIVEM_HOST	127.0.0.1	FiveM クライアントを実行しているマシン（devcon ホスト）
FIVEM_EXECUTABLE	%LOCALAPPDATA%\FiveM\FiveM.exe	launch ツールで使用する FiveM.exe
FIVEM_CLIENT_DEVCON_PORT	29200 then 29300	クライアントの devcon ポートを上書きします
FIVEM_RCON_ADDRESS	FIVEM_HOST:30120	FXServer のゲームポート（UDP RCON + getinfo）
FIVEM_RCON_PASSWORD	—	server.cfg の rcon_password と一致します。server_command に必要です
FIVEM_SERVER_LOG	—	FXServer のリダイレクトされた標準出力のパスです。サーバー側の read_console / wait_for_console を有効にします。v0.5 以降、ブリッジでは不要です（結果はインバンドでポーリングします）。v0.5 より前のフォールバックトランスポートです
FIVEM_MCPB_TOKEN	—	サーバー上の mcpb_token と一致します。すべてのブリッジリクエストとともに送信されます
FIVEM_CONSOLE_CAPACITY	5000	リングバッファに保持するクライアントコンソールの行数
FIVEM_QUIET_MS	400	この時間だけ出力が途切れたら、コマンド出力が完了したと見なします
FIVEM_COMMAND_TIMEOUT_MS	5000	client_command の出力を待つデフォルトの最大時間
FIVEM_MCP_DEBUG	—	1 を指定すると、devcon フレームと RCON の往復を stderr にトレースします

ツール

ツール	機能
status	接続状態：RCON、ログファイル、クライアント devcon。最初に呼び出してください
server_info	UDP 経由の getinfo — ホスト名、プレイヤー数、最大クライアント数、プロトコル、ゲームビルド。認証情報は不要です。
server_command	UDP RCON 経由で任意のサーバーコンソールコマンドを実行し、取得した出力を返します
client_command	実行中の Legacy クライアントの F8 コンソールに入力します（フォーカスを奪いません）。これはローカルコンソールコマンド層です — connect、quit、ツール関連などが対象です。RegisterCommand のチャットコマンドは別のシステムです（コンソール権限で実行する server_command、または入力／ブリッジツールを使用してください）。出力されたコンソール行を返します
read_console	最近の行を取得します。クライアントの場合はライブ devcon ストリーム（afterSeq によるページング）、サーバーの場合は FIVEM_SERVER_LOG の末尾です。channel／contains／pattern で絞り込めます
wait_for_console	正規表現に一致する行が現れるまで待機します — アサーションの基本機能です
list_commands	クライアントコンソールが認識するすべてのコマンド（devcon ハンドシェイク）
launch	FiveM を起動します。必要に応じて host:port に直接接続します（デフォルト：設定済みのサーバー）
quit_game	devcon 経由で正常に quit します。force を指定すると FiveM のプロセスツリーを強制終了します
window_status	ゲームウィンドウの有無、タイトル、pid、rect、フォアグラウンド状態
focus_window / restore_focus	ゲームを前面に表示／ウィンドウにフォーカスを戻します。入力ツールは自動的にフォーカスします
screenshot	ゲームウィンドウの PNG（PrintWindow、フォールバックは screen-BitBlt）。縮小されます — デフォルトは 900、任意で crop rect を指定できます。撮影するたびにセッション全体でトランスクリプトのトークンを消費するため、テキストによる確認を優先し、撮影範囲は小さくしてください
press_key / hold_key / release_key	実際のスキャンコード入力 — GTA の DirectInput は VK のみの注入を無視します。プロセスが終了すると、押し続けているキーは解放されます
type_text	リテラルな Unicode イベント — F8 コンソールとチャット NUI が読み取る入力チャネルです
mouse_move / click / scroll	相対移動でカメラを操作し、絶対座標で NUI 用にカーソルを配置します
wait	アクション間で待機します（ロード画面、歩行サイクル）
read_client_log	FiveM のインストール先にある最新の CitizenFX_log_*.log
bridge	mcpb ブリッジリソースを呼び出します。サーバー側では ping、players、poll、call_export、trigger_event、クライアント側では ping、position、teleport、freeze、call_native、send_nui、nui_callback を実行します。op は選択したターゲットに対して検証されます

プロンプト

実機で検証済みのループを凝縮した、2 つのワークフローが MCP プロンプトとして用意されています。

• test_resource(resource, expectations?) — クリーンな再起動 → コンソールのエラースキャン → クライアント側のスキャン → ゲーム内シナリオ（キー入力、スクリーンショット、ブリッジ状態）→ 証拠に基づく PASS／FAIL レポート。不確かで検証できないことは、明確にその旨を伝えます。
• smoke_check — 1 回の迅速な確認：接続、どのサーバーか、両側のエラー末尾、 ウィンドウとスクリーンショット、保存済みクライアントログ。各行を OK／WARN／DOWN で示します。

ブリッジリソース（bridge/）

ネイティブ機能、NUI コールバック、位置情報などのクライアント側テストは、devcon と RCON では 実行できません。このギャップを埋める小さな補助リソースが、このリポジトリに同梱されています。

# on the dev server
cp -r bridge/ <server-data>/resources/mcpb     # or a junction
# server.cfg:
#   ensure mcpb
#   setr mcpb_enabled true
#   setr mcpb_token <a-random-token>
#   setr mcpb_event_allowlist  my:event,other:event      # trigger_event may fire only these
#   setr mcpb_export_allowlist myres:*,other:method       # optional; empty = any export
#   setr mcpb_native_allowlist SetEntityHealth,GetGameTimer   # optional; empty = any native
#   setr mcpb_client_timeout_ms 8000                      # a silent client fails fast
#   setr mcpb_verbose true                                # echo requests to both consoles

そして、FIVEM_MCPB_TOKEN を使ってこのサーバーからリソースを指定します。次に：

bridge { target: "client", src: 1, op: "position" }
bridge { target: "server", op: "call_export", args: "{\"resource\":\"myres\",\"method\":\"money\",\"args\":[1]}" }

クライアントの結果は、RCON 経由でポーリングされるインバンドキューから返されます（v0.5 以降は約 100 ms 間隔。ログファイルは不要です。v0.5 より前のリソースでは、引き続きログ末尾へのフォールバックが使用されます）。

開発サーバー専用です。 mcpb_enabled のデフォルトは false で、コマンドはコンソール／RCON からのみ受け付けられ（プレイヤーからは実行できません）、設定時にトークンが確認されます。ただし、call_native の安全性は、実行元であるコンソールとまったく同じです。RCON とこのブリッジは、重要なものには接続しないでください。SECURITY.md を参照してください。ワイヤー仕様の全文：docs/protocol.md §4。

一般的なループ（エージェントが行うこと）

1. server_command: "ensure my-resource"
2. wait_for_console: target=server, pattern="Started resource my-resource|Error"
3. client_command: "connect localhost:30120" で接続処理を実行し、その後 read_console: target=client で、サーバーログには出力されないクライアント側のコンソール出力を取得します。

セキュリティに関する注意 — 公開する前にお読みください

• クライアントの devcon ソケットには認証がありません。 接続できる人は誰でも、そのゲームクライアント上でローカルのコンソールコマンド（connect、quit など）を実行できます。FiveM は、クライアントを -devcon 付きで起動しない限り、これを 127.0.0.1 にバインドします（-devcon 付きの場合は 0.0.0.0）。このツールはループバックのデフォルトを前提としており、それ以上は必要ありません。トンネル接続しないでください。
• RCON はサーバーの管理者権限の要です。 rcon_password は強力なものにしてください。FIVEM_RCON_PASSWORD は MCP 設定に記載されるため、そのファイルも同様に保護してください。
• 現行ビルドの FXServer には、サーバー側の devcon ソケットがありません（2026-09-02 に確認済み）。そのため、サーバー側では RCON とログ末尾を使用します。
• server_command は、何かを exec できる時点で、エージェントにそのマシンの root 権限を与えるものとして扱ってください。開発サーバーに対してのみ実行してください。

開発

pnpm test        # vitest: fake devcon/rcon servers, byte-level SendInput/PNG checks, bridge contract, docs drift
pnpm typecheck
pnpm check       # biome
pnpm build       # -> dist/
pnpm run ci      # all of the above (plain `pnpm ci` is a pnpm builtin and errors)

リリース手順：新しいバージョン見出しの下に Unreleased の変更履歴を移動し、pnpm version <patch|minor|major> を実行します（server.json とブリッジのマニフェストを更新・同期し、タグを作成します）。次に、手元のマシンから npm publish を実行します（prepublishOnly が完全なゲートを実行します）。最後に git push --follow-tags を実行します。続いて Release ワークフローがゲートを再実行し、CHANGELOG.md から GitHub Release を作成して、MCP Registry にバージョンを登録します。 CONTRIBUTING.md を参照してください。

実サーバー／ゲームに対する実機検証：pnpm live:probe、live:e2e、live:m2、live:m3。

ワイヤープロトコル（DevCon フレーム、RCON／getinfo OOB データグラム、Cfx 文字列ハッシュ）は、オープンソースの CitizenFX サーバー citizenfx/fivem@03dcc562 を基に、docs/protocol.md でバイト単位に詳しく説明されています。実機検証済み：RCON の応答形式、getinfo の応答、および >8 バイトのチャレンジが破棄されることを、2026-09-02 に実際の FXServer で確認しました。

ライセンス

MIT。FiveM／CitizenFX の名称は Cfx.re の商標です。このプロジェクトは Cfx.re と提携しておらず、同社の承認も受けていません。