dolu_fivem_mcp

Build, inspect and test FiveM resources without leaving your coding assistant.

A standalone MCP server connecting your assistant to the game, the server and NUI.

Quick start  ·  Features  ·  Tool reference  ·  Download

Go beyond writing code. Let your assistant run a snippet, inspect the result, interact with a live interface and capture what actually appears in-game. 35 tools cover the full development loop, from resource management to repeatable tests with screenshot evidence.

Features

Standalone by design. No framework, txAdmin, screenshot-basic, Yarn or webpack resource required. Prebuilt releases are ready to install. Uses the official MCP SDK and Streamable HTTP.

Local development only. This is not a sandbox: an assistant can execute arbitrary code. There is no HTTP authentication. The server listens only on 127.0.0.1 and checks Host/Origin headers, but any local process that can reach it can use the tools. Never expose it through a proxy or tunnel, or install it on a public server.

Requirements

• A recent local FiveM server.

• An AI assistant that supports MCP Streamable HTTP.

For client tools, NUI and screenshots, connect your FiveM client to the local server. NUI and screenshots also need the client on the same PC, connected through 127.0.0.1, with CEF DevTools accessible.

Quick start

1. Install

Place this resource in your server's resources directory, keeping the folder name dolu_fivem_mcp.

Using a prebuilt runtime archive? Download the .tgz asset from Releases, extract its package folder as dolu_fivem_mcp and skip the build commands below. GitHub's automatic "Source code" archives are not prebuilt.

Building from source? Install Node.js 22 or newer and npm, then run these commands from the resource folder:

npm ci
npm run build

The build creates the runtime bundles and the .yarn.installed marker. Dependencies are bundled, so FXServer does not need to install them at startup.

2. Grant permissions and start the resource

Add these lines to your server configuration:

add_ace resource.dolu_fivem_mcp command allow
add_ace group.admin dolu_fivem_mcp.use allow

ensure dolu_fivem_mcp

These are two separate permissions:

• resource.dolu_fivem_mcp command lets the resource run server commands.

• dolu_fivem_mcp.use allows a player to be targeted by client tools.

The player must actually belong to group.admin, or receive dolu_fivem_mcp.use through another existing principal. Being a txAdmin or framework administrator does not automatically grant it. See config.example.cfg for an example of a direct player grant.

3. Connect your assistant

For hosts that use a mcpServers configuration:

{
  "mcpServers": {
    "dolu_fivem_mcp": {
      "type": "http",
      "url": "http://127.0.0.1:3210/mcp"
    }
  }
}

The exact configuration format depends on your assistant. Use its HTTP transport, not stdio or the older HTTP+SSE transport. An assistant running in a VM, WSL or on another machine does not automatically share this loopback address.

4. Check the connection

Ask your assistant:

Check the FiveM MCP status, list the players, and run read-only diagnostics on the ready client.

The relevant tools are status, list_players and diagnose. Pass runChecks: true to diagnose to test JavaScript and Lua native calls; capture: true also tests a small screenshot.

Always discover the current player ID instead of assuming it is 1. Most client tools can select the player automatically when exactly one authorized client is ready.

Common tasks

These examples are tool arguments, not full HTTP requests. Your assistant normally constructs the calls for you.

Run code

Use execute_server for a read-only JavaScript check:

{
  "language": "javascript",
  "code": "return { resource: ctx.resource, state: GetResourceState(ctx.resource) };"
}

Use execute_client to read the player's position in Lua:

{
  "language": "lua",
  "code": "return GetEntityCoords(PlayerPedId())",
  "timeoutMs": 5000
}

Add playerId when selecting a specific client. For a long-running snippet, set wait: false, keep the returned ID, then use get_execution or cancel_execution. Logs are available while the snippet is running.

Server/client snippets run inside dolu_fivem_mcp, not inside another resource's private variables. Use natives, exports and events to interact with other resources. Use your editor to change source files.

Work with a NUI page

NUI is FiveM's browser-based interface layer. These tools use its local CEF DevTools connection.

1. Call list_nui_frames to find the resource and frame.

2. Call nui_snapshot to inspect its elements.

3. Use nui_interact to click, fill, select, press a key, hover or scroll.

4. Use nui_wait_for to wait for the expected element state or text.

For example, to fill an input:

{
  "resource": "my_inventory",
  "frameId": "FRAME_ID_FROM_LIST_NUI_FRAMES",
  "interaction": {
    "action": "fill",
    "selector": "#search",
    "text": "water"
  }
}

Provide frameId when a resource has multiple frames. Snapshot references can replace selectors, but may become stale after a page change or restart; take a new snapshot rather than blindly retrying an action.

Hidden, disabled, obscured or ambiguous targets are rejected. The target UI may need to acquire its own focus for CDP input. The invisible dolu_fivem_mcp bridge never takes keyboard or mouse focus.

To investigate UI problems, use start_nui_observation, read events with read_nui_observation, then call stop_nui_observation. Console and exception capture are enabled by default; network metadata requires network: true. Observations last at most 60 seconds and retain at most 500 events.

Take a screenshot

Call game_screenshot:

{
  "includeNui": true,
  "maxWidth": 1280,
  "format": "jpeg",
  "quality": 0.85
}

Both game screenshot modes require local CEF DevTools. Images are returned directly to the assistant; the resource does not automatically save or upload them.

Game and NUI captures are taken sequentially, so fast animations may not line up perfectly. Other Chromium targets and OS overlays are not guaranteed to appear. If an image exceeds the size limit, reduce maxWidth or use JPEG.

Tool reference

The server exposes 35 tools. Your assistant can discover their full argument schemas with tools/list.

The MCP resource fivem://dolu_fivem_mcp/execution-guide provides execution guidance. The test_resource prompt suggests a development workflow.

Execution: JavaScript snippets are async function bodies with return and await; require is server-only. Lua supports multiple return values. Use ctx.sleep(ms) (await in JavaScript), ctx.alive() and ctx.onCleanup(...) for cooperative work. Cleanup callbacks must be short and synchronous. After Node I/O, run server natives through await ctx.game(() => nativeCall()).

Results and logs: Structured results are under structuredContent.result; completed executions include outcome.values, logs and timing. Special values such as Lua nil have explicit serialized representations. Use executionId to filter logs and pass nextCursor back as after to read new entries. Client logs cover snippets, not the entire F8 console.

Entity inspection: Choose target: "server" or "client". Handles are temporary and local to that runtime; they are not network IDs. Server entity searches require OneSync and an explicit position, without playerId. Searches are limited to 500 metres and 100 returned entities. Resource inspection lists declared exports, not all dynamic exports.

Scenarios: run_scenario runs ordered tool steps with equals, contains or exists assertions and optional cleanup steps. Set a resource and, when needed, a player. The first failure skips subsequent main steps; declared cleanup is still attempted. Limits: one scenario at a time, 12 main steps, 4 cleanup steps, 60 seconds for the main work and a separate 10-second cleanup budget. Reports and image evidence expire after 15 minutes or a resource restart.

Direct HTTP: Send JSON-RPC POST requests to /mcp with Content-Type: application/json and Accept: application/json, text/event-stream. The transport is stateless; no session token or Authorization header is needed.

Configuration and troubleshooting

All settings are optional. Defaults are shown below; see config.example.cfg.

After changing configuration or rebuilding, run restart dolu_fivem_mcp from the FXServer console, outside an active MCP call. Watch mode only rebuilds files; it does not restart the resource.

Important limits

• Timeout and cancellation are cooperative. They do not guarantee that arbitrary code stops or that its effects are undone. Do not automatically retry actions with side effects.

• Execution code, output, logs and histories are bounded. Snippets have a maximum 60-second timeout and 100 captured log lines.

• The management tools refuse to stop or restart dolu_fivem_mcp itself. Arbitrary code is still powerful enough to disrupt the server: this is not a security sandbox.

• NUI snapshots, logs and screenshots may contain sensitive information. Network observations omit bodies, headers and cookies, and strip credentials, queries and fragments from URLs; this is not universal secret filtering.

• NUI control is local-only. Some transformed, zoomed or separate-target iframe layouts are unsupported. Behaviour can vary with FiveM artifacts, client state and GPU.

Development

Built with TypeScript, the official MCP SDK v2, Zod and esbuild, with small Lua executors. The manifest uses FiveM's Node.js 22 runtime. Current FiveM artifacts use Lua 5.4 by default; lua54 'yes' is deprecated. Experimental OAL is intentionally disabled to preserve native-call compatibility.

Live tests include deliberate snippet errors and timeouts. To save a report, use npm run test:live -- --output C:\temp\dolu-fivem-mcp-report.json (the parent directory must exist).

Disposable resource: Copy tests/fixtures/dolu_fivem_mcp_test beside dolu_fivem_mcp, run refresh in the FXServer console, and leave the fixture stopped. Then run:

npm run test:live -- --fixture

Resource start/restart/stop actions target only the fixture. The test temporarily gives it input focus, releases it during cleanup, and stops it. It refuses to take over an already running fixture. You can remove the copied folder after the test; the script does not remove it for you.

Official SDK client check:

npm exec --yes --package=@modelcontextprotocol/client@2.0.0 -- node scripts\client-check.cjs

This uses npm's cache without adding a runtime dependency. It tests the live connection, tools, structured results, errors, images, MCP resources and prompts. It does not configure applications such as VS Code or Claude Desktop.

Runtime archive: Extract the archive's package directory as dolu_fivem_mcp. It contains the bundles, Lua executor, technical page, manifest, .yarn.installed and documentation. It is already compiled; build and test commands belong in a source checkout, not in this archive.

Cfx builders: Yarn checks whether .yarn.installed is at least as recent as package.json. Every successful build refreshes this generated marker, and the runtime archive includes it. Keep the marker when deploying; rerun the build after changing package.json or if copying files makes it newer than the marker. The Cfx webpack builder requires webpack_config metadata, which this resource does not declare.

CI and releases: Check runs tests and builds on Windows and Linux with Node.js 22. Release validates version tags and publishes the prebuilt runtime archive. To release, update the versions in package.json, package-lock.json, fxmanifest.lua and src/shared/protocol.ts, run npm run check, then push a matching vX.Y.Z tag.

To retry publication, run the Release workflow manually from main with the existing version tag. Existing archives and release notes are preserved; a missing archive is uploaded without recreating the release.

Validation scope: Automated tests cover simulated FiveM/CDP behaviour, and the live scripts exercise the running game. Player disconnections, ACE changes, minimization, resolution changes and GPU failures require separate, deliberate testing. Passing these checks is not a guarantee for every client, host or hardware configuration.

License

MIT, copyright Dolu. Bundled dependencies retain their own licenses, included in THIRD_PARTY_NOTICES.txt.