fivem-mcp

An MCP (Model Context Protocol) server that lets AI agents — Claude, Qwen, or anything that speaks MCP — build, run and live-test FiveM servers from the same machine.

It is the missing test layer for the "did it actually work in-game?" question: the agent can run real console commands, watch both the server log and the live F8 console of a running FiveM client, wait for specific output, and react — without you touching the keyboard.

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

Status

v0.5 drives the whole loop: server console (RCON), client F8 console (devcon), the game window (launch, focus, screenshot, keyboard/mouse) and an in-game bridge (mcpb) for natives, exports and NUI callbacks — plus ready-made test prompts. Tools answer with structured content, carry MCP annotations, and stop as soon as the client cancels. All of it live-verified against a real FXServer + FiveM Legacy client (see docs/plan.md and scripts/live-*.mjs).

Where it is published

Channel	Address
npm	fivem-mcp-server — npx -y fivem-mcp-server
MCP Registry	io.github.ziyacivan/fivem-mcp (registry.modelcontextprotocol.io)
Source releases	GitHub Releases, tagged vX.Y.Z

The repository's GitHub Packages sidebar is deliberately empty: the artifact lives on npmjs.com, not GitHub Packages — the latter would force a scoped @ziyacivan/ package name and a second registry for no benefit.

Requirements

• Node 22+ (Windows, macOS or Linux for the server side; the client devcon works wherever the FiveM client runs — this tool must run on that machine for the client_* tools since devcon binds to localhost by default).
• A running FXServer you administer (rcon_password set for server_command).
• The Legacy FiveM client for the client-console tools (Enhanced removed the client devcon ports; see docs/protocol.md).
• The keyboard/mouse/screenshot tools are Windows-only and run on the machine with the game. On other platforms every tool except those is served normally.

Install

Published on npm — no clone needed. Add it to Claude Code in one line:

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 = available in every project; drop it for a per-project entry. Verify with claude mcp get fivem — status should read ✓ Connected. Remove with claude mcp remove fivem -s user.)

For a shared project config, put .mcp.json in the repo root and commit it — Claude Code asks to approve it on first open, and env values can be interpolated from your local .env-less shell via ${VAR} expansion:

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

For Claude Desktop (or any client with JSON config), add to claude_desktop_config.json:

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

The server is also listed in the MCP Registry as io.github.ziyacivan/fivem-mcp. Building from source (development):

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

Configuration (environment)

Variable	Default	Meaning
FIVEM_HOST	127.0.0.1	Machine running the FiveM client (devcon host)
FIVEM_EXECUTABLE	%LOCALAPPDATA%\FiveM\FiveM.exe	FiveM.exe for the launch tool
FIVEM_CLIENT_DEVCON_PORT	29200 then 29300	Override the client devcon port
FIVEM_RCON_ADDRESS	FIVEM_HOST:30120	FXServer game port (UDP RCON + getinfo)
FIVEM_RCON_PASSWORD	—	Matches rcon_password in server.cfg; needed by server_command
FIVEM_SERVER_LOG	—	Path to FXServer's redirected stdout; enables server-side read_console / wait_for_console. Not needed by the bridge since v0.5 (results poll in-band) — it is the pre-0.5 fallback transport
FIVEM_MCPB_TOKEN	—	Matches mcpb_token on the server; sent with every bridge request
FIVEM_CONSOLE_CAPACITY	5000	Client console lines kept in the ring buffer
FIVEM_QUIET_MS	400	Consider command output done after this quiet period
FIVEM_COMMAND_TIMEOUT_MS	5000	Default max wait for client_command output
FIVEM_MCP_DEBUG	—	1 traces devcon frames and RCON round-trips on stderr

Tools

Tool	What it does
status	Connection state: RCON, log file, client devcon. Call first.
server_info	getinfo over UDP — hostname, players, max clients, protocol, game build. No credentials needed.
server_command	Any server console command over UDP RCON; returns the captured output.
client_command	Types into the F8 console of a running Legacy client over devcon (nothing steals focus). This is the local console command layer — connect, quit, tooling; RegisterCommand chat commands are a different system (use server_command, which runs with console privileges, or the input/bridge tools). Returns the console lines it printed.
read_console	Recent lines: client = live devcon stream (with afterSeq paging), server = tail of FIVEM_SERVER_LOG. Filter by channel/contains/pattern.
wait_for_console	Block until a line matching a regex appears — your assertion primitive.
list_commands	Every command the client console knows (devcon handshake).
launch	Start FiveM, optionally straight into host:port (default: the configured server).
quit_game	Graceful quit over devcon; force kills the FiveM process tree.
window_status	Game window existence, title, pid, rect, foreground state.
focus_window / restore_focus	Bring the game forward / give focus back to your window. Input tools focus automatically.
screenshot	PNG of the game window (PrintWindow, screen-BitBlt fallback). Downscaled — default 900, optional crop rect. Every shot costs transcript tokens all session: prefer text probes, shoot small.
press_key / hold_key / release_key	Real scan-code input — GTA's DirectInput ignores VK-only injection. Held keys are released if the process dies.
type_text	Literal Unicode events — the channel the F8 console and chat NUI read.
mouse_move / click / scroll	Relative moves drive the camera; absolute coordinates position the cursor for NUI.
wait	Pause between actions (loading screens, walk cycles).
read_client_log	The newest CitizenFX_log_*.log from the FiveM install.
bridge	Invoke the mcpb bridge resource: ping, players, poll, call_export, trigger_event (server half) and ping, position, teleport, freeze, call_native, send_nui, nui_callback (client half). op is validated against the chosen target.

Prompts

Two workflows are shipped as MCP prompts, distilled from the live-verified loops:

• test_resource(resource, expectations?) — clean restart → console error scan → client-half scan → in-game scenario (keys, screenshot, bridge state) → evidence-backed PASS/FAIL report where anything unverifiable is said so out loud.
• smoke_check — one fast sweep: connections, which server, error tails on both sides, window + screenshot, persisted client log. OK/WARN/DOWN per line.

The bridge resource (bridge/)

Client-side testing (natives, NUI callbacks, position) is outside what devcon and RCON can reach — the small companion resource closes that gap and ships in this repo.

# 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

and point this server at it with FIVEM_MCPB_TOKEN. Then:

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

Client results come back through an in-band queue polled over RCON (~100 ms granularity since v0.5 — no log file needed; pre-0.5 resources still fall back to the log tail).

Dev servers only. mcpb_enabled defaults to false, the command is accepted only from the console/RCON (never from a player), and the token is checked when set — but call_native is exactly as safe as the console it runs behind. Keep RCON and this bridge off anything you care about; see SECURITY.md. The full wire contract: docs/protocol.md §4.

Typical loop (what an agent does)

1. server_command: "ensure my-resource"
2. wait_for_console: target=server, pattern="Started resource my-resource|Error"
3. client_command: "connect localhost:30120" drives the join itself, then read_console: target=client catches client-side console output that never reaches the server log.

Security notes — read before exposing anything

• The client devcon socket has no authentication. Anyone who can reach it can run local console commands in that game client (connect, quit, ...). FiveM binds it to 127.0.0.1 unless the client is started with -devcon (then 0.0.0.0); this tool assumes the loopback default and never needs more. Do not tunnel it.
• RCON is the server's admin root. Keep rcon_password strong; FIVEM_RCON_PASSWORD lives in your MCP config — protect that file the same way.
• FXServer itself has no server-side devcon socket on current builds (verified 2026-09-02), which is why the server half is RCON + log tail.
• Treat server_command as giving the agent root on your box the moment it can exec anything; run it only against development servers.

Development

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)

Releasing: move the Unreleased changelog notes under the new version heading, then pnpm version <patch|minor|major> (bumps and syncs server.json + the bridge manifest, and tags), npm publish from your machine (prepublishOnly runs the full gate), and git push --follow-tags. The Release workflow then re-runs the gate, creates the GitHub Release from CHANGELOG.md, and registers the version with the MCP Registry. See CONTRIBUTING.md.

Live verification against a real server/game: pnpm live:probe, live:e2e, live:m2, live:m3.

The wire protocol (DevCon frames, RCON/getinfo OOB datagrams, the Cfx string hash) is documented byte-by-byte in docs/protocol.md, derived from the open-source CitizenFX server, citizenfx/fivem@03dcc562. Live-verified: RCON reply format, getinfo response and the >8-byte challenge drop were confirmed against a real FXServer on 2026-09-02.

License

MIT. The FiveM/CitizenFX name is a trademark of Cfx.re; this project is not affiliated with or endorsed by Cfx.re.