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

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)

Tools

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).