fivem-mcp-server
Provides tools for building, running, and live-testing FiveM servers through RCON, client devcon, game window input/screenshot, and an in-game bridge for natives, exports, and NUI callbacks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@fivem-mcp-server restart the mcpb resource and check the client console for errors"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 logStatus
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).
Related MCP server: Universal Computer Control MCP
Where it is published
Channel | Address |
npm | fivem-mcp-server — |
MCP Registry |
|
Source releases | GitHub Releases, tagged |
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_passwordset forserver_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 copyConfiguration (environment)
Variable | Default | Meaning |
|
| Machine running the FiveM client (devcon host) |
|
| FiveM.exe for the |
|
| Override the client devcon port |
|
| FXServer game port (UDP RCON + getinfo) |
| — | Matches |
| — | Path to FXServer's redirected stdout; enables server-side |
| — | Matches |
|
| Client console lines kept in the ring buffer |
|
| Consider command output done after this quiet period |
|
| Default max wait for |
| — |
|
Tools
Tool | What it does |
| Connection state: RCON, log file, client devcon. Call first. |
|
|
| Any server console command over UDP RCON; returns the captured output. |
| Types into the F8 console of a running Legacy client over devcon (nothing steals focus). This is the local console command layer — |
| Recent lines: client = live devcon stream (with |
| Block until a line matching a regex appears — your assertion primitive. |
| Every command the client console knows (devcon handshake). |
| Start FiveM, optionally straight into |
| Graceful |
| Game window existence, title, pid, rect, foreground state. |
| Bring the game forward / give focus back to your window. Input tools focus automatically. |
| PNG of the game window (PrintWindow, screen-BitBlt fallback). Downscaled — default 900, optional |
| Real scan-code input — GTA's DirectInput ignores VK-only injection. Held keys are released if the process dies. |
| Literal Unicode events — the channel the F8 console and chat NUI read. |
| Relative moves drive the camera; absolute coordinates position the cursor for NUI. |
| Pause between actions (loading screens, walk cycles). |
| The newest |
| Invoke the |
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 consolesand 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)
server_command: "ensure my-resource"wait_for_console: target=server, pattern="Started resource my-resource|Error"client_command: "connect localhost:30120"drives the join itself, thenread_console: target=clientcatches 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.1unless the client is started with-devcon(then0.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_passwordstrong;FIVEM_RCON_PASSWORDlives 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_commandas giving the agent root on your box the moment it canexecanything; 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.
Available Tools
23 toolsbridgeInvoke a bridge operation (mcpb resource)ADestructive
Runs an operation through the mcpb bridge resource — the half neither devcon nor RCON can reach. Server ops (target=server): ping, players, poll, call_export, trigger_event, wait; call_export {resource, method, args}, trigger_event {event, args, toClient?, player?} (event names must be in mcpb_event_allowlist). Client ops (target=client, needs src): ping, position, teleport, freeze, call_native, send_nui, nui_callback; teleport {x,y,z,heading?}, freeze {freeze}, call_native {name, args}, send_nui {resource, message, event?}, nui_callback {resource, endpoint, payload}. Client results are collected in-band via the bridge's poll queue — no FIVEM_SERVER_LOG needed. The bridge must be installed, started and enabled (mcpb_enabled true).
Inputs: op (required), target (required), src, args, +1 more. Returns: op, data, target
clickMouse clickA
Click at the current cursor position (position it with mouse_move absolute first for NUI).
Inputs: button, double.
client_commandRun a FiveM client (F8) console commandADestructive
Type a LOCAL console command into the running Legacy client's F8 console over devcon — no screen focus needed, nothing is typed into the game window. This is the process's console context (connect, quit, tooling commands), NOT the chat command layer: commands registered with RegisterCommand are chat commands and live in a different system (run them through server_command, which has console privileges, or drive the chat UI with the M2 input tools). Waits until output goes quiet and returns the lines the client console printed.
Inputs: command (required), timeoutMs, waitForOutput.
focus_windowBring the game to the foregroundA
Restores/minimizes-out if needed and steals foreground (remembering the previous window for restore_focus). Every input/screenshot tool calls this automatically.
Inputs: no named parameters.
hold_keyHold a key downA
Key stays pressed until release_key. Use for movement (W) and camera. Key name: W A S D E F Q space enter esc tab shift ctrl alt arrows up down left right, f1-f12, letters/digits. Held keys are released if this process exits.
Inputs: key (required).
launchStart the FiveM clientA
Launch FiveM, optionally straight into a server via the fivem://connect link. Default target is the configured game port. Returns immediately — watch window_status/client_command to see when the game is up.
Inputs: connectTo.
list_commandsList client console commandsARead-onlyIdempotent
The devcon handshake streams every command the client console knows (CVAR frames). For server commands, run 'help' through server_command instead. Filter with a case-insensitive substring.
Inputs: contains. Returns: count, commands
mouse_moveMove the mouseA
Relative dx/dy drives the in-game camera; absolute x/y (screen pixels) positions the real cursor for NUI elements.
Inputs: x, y, dx, dy.
press_keyTap a keyA
Press and release a key (scan codes — what GTA's DirectInput/raw input reads). Key name: W A S D E F Q space enter esc tab shift ctrl alt arrows up down left right, f1-f12, letters/digits.
Inputs: key (required), holdMs.
quit_gameClose the FiveM clientADestructive
Graceful path: prints 'quit' to the client console over devcon and waits for the game to close (nothing is typed into the window). force: true kills the FiveM process tree instead — use it only when the game is wedged.
Inputs: force.
read_client_logRead the FiveM client log fileARead-onlyIdempotent
Tail the newest CitizenFX_log_*.log under the FiveM install — the same stream as read_console(client) but persisted across sessions, without the channel tags.
Inputs: limit, pattern, contains. Returns: file, lines, matched
read_consoleRead recent console outputARead-onlyIdempotent
Return recent console lines without running anything. For 'client', reads the devcon line buffer (live from the moment this server first connected; supports afterSeq paging). For 'server', tails FIVEM_SERVER_LOG (FXServer's redirected stdout) — the last 512 KB, filtered; afterSeq is not supported there.
Inputs: target (required), limit, channel, pattern, +2 more. Returns: lines, matched, nextSeq, clientError
release_keyRelease held key(s)A
Release one held key, or all of them with key='all'.
Inputs: key (required).
restore_focusGive focus back to the previous windowA
Returns foreground to whatever window was focused before this tool focused the game.
Inputs: no named parameters.
screenshotCapture the game windowA
PNG of the FiveM window (PrintWindow with PW_RENDERFULLCONTENT; falls back to a screen BitBlt of the window rect when the swapchain returns black, which means whatever covers the window is also captured — the game is focused first). Downscaled so vision models can read it cheaply. COST WARNING: every screenshot stays in the transcript and is re-sent on every later turn - many shots multiply session latency. Prefer text probes (read_console, wait_for_console, bridge ops); when pixels are the evidence, keep maxSide small (640 suffices for layout checks) and crop to the panel of interest.
Inputs: crop, maxSide.
scrollMouse wheelA
Scroll the wheel (positive = up). NUI lists respond to it.
Inputs: amount (required).
server_commandRun an FXServer console commandADestructive
Execute a command on the server console over UDP RCON (any command the console accepts: ensure/stop/restart, convars, registered commands). The reply carries the command's captured console output. Needs rcon_password on the server and FIVEM_RCON_PASSWORD here; rate-limited server-side (~5 burst).
Inputs: command (required).
server_infoQuery server identity (no credentials)ARead-onlyIdempotent
Ask the server's getinfo out-of-band endpoint: hostname, players online, max clients, protocol, game build. Works without rcon_password; use it to confirm which server you are pointed at.
Inputs: no named parameters. Returns: object
statusConnection statusARead-onlyIdempotent
Report RCON configuration for the server, the devcon connection to the FiveM client console, and the server log-file tailer. Call this first.
Inputs: no named parameters. Returns: host, client, server, clientDevconPorts
type_textType literal textA
Sends Unicode key events — the F8 console and chat/NUI inputs read these normally. Open the target input first (e.g. client_command to focus, or a chat key like T). Does not press Enter.
Inputs: text (required).
waitPauseARead-onlyIdempotent
Sleep between actions — loading screens, walk cycles, held-key sequences.
Inputs: ms (required).
wait_for_consoleWait for a console line to appearARead-onlyIdempotent
Block until a line matching a regex appears. 'client' watches the live devcon stream; 'server' polls FIVEM_SERVER_LOG for newly written lines (only lines appended after the call count). Use after a fire-and-forget command, to watch for a resource's startup banner, an error, or a scripted RESULT: line.
Inputs: target (required), pattern (required), afterSeq, timeoutMs. Returns: seq, channel, message
window_statusGame window stateARead-onlyIdempotent
Whether the FiveM game window exists, its title/pid, on-screen rect, and whether it is the foreground window. Input/screenshot tools focus it automatically.
Inputs: no named parameters. Returns: pid, rect, found, title, +1 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Most tools target distinct capabilities (input vs window vs console vs bridge), and descriptions go to lengths to clarify boundaries (e.g., server_command vs client_command vs the chat layer). However there is genuine overlap among the read/inspect tools (read_console, read_client_log, list_commands) and between the multi-purpose bridge and server_command/client_command, which could still cause misselection.
Many tools follow a verb_noun or clear noun pattern (read_console, hold_key, focus_window, window_status), but others are bare verbs or nouns (bridge, status, launch, click, scroll, wait) with no single governing convention. It stays readable but is a mixed bag rather than a predictable scheme.
23 tools is on the heavy side, but the surface spans genuinely separate domains — RCON server control, devcon client console, the mcpb bridge, raw input, and window/screenshot management — so nearly every tool earns its place. It is slightly over what feels ideal but not padded.
Coverage is broad and coherent: server and client command execution, console reading/waiting, bridge ops, full keyboard/mouse/text input, window focus, and screenshots. Minor gaps remain, such as a dedicated chat-send or screenshot-crop helper, but agents can work around these with existing primitives.
Maintenance
Related MCP Connectors
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Reach your own computers from any AI app: files, commands, screen and mouse, approvals and alerts.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to read and administer FiveM/RedM game servers via txAdmin, supporting queries about server status, players, bans, and actions like announcements, resource control, and bans.MIT
- AlicenseBqualityBmaintenanceThis server enables AI agents to operate Windows and Linux computers by observing the screen, understanding the UI through accessibility, OCR, and vision, and performing mouse, keyboard, window, clipboard, and system actions with verification and recovery.292MIT
- AlicenseNot gradedqualityBmaintenanceEnables local FiveM development by letting an AI assistant execute JavaScript/Lua on the server or client, automate NUI interactions, capture game screenshots, manage resources, and run repeatable tests with screenshot evidence.6MIT
- AlicenseAqualityDmaintenanceEnables AI agents to connect to one or more running Roblox game clients to execute Lua code, decompile and search scripts, browse instances with CSS-like selectors, intercept and block remotes, drive GUIs, and capture screenshots through a local dashboard and bridge.21MIT