FiveM MCP

A focused MCP server for FiveM teams who want faster scaffolding, safer file edits, and stronger UI/NUI starting points.

<p align="left"> <strong>Open source</strong> • Built for local stdio workflows • Designed for Cursor, Trae, and Claude </p>

Why This Exists

FiveM MCP was built to make AI agents actually useful inside a FiveM workflow.

Instead of giving a generic assistant a pile of loose files and hoping for the best, this server exposes a practical toolkit for:

• creating new FiveM resources
• adding or scaffolding NUI quickly
• generating UI templates with multiple variants and themes
• editing files more safely with hash-aware and line-based operations
• giving MCP clients enough structured context to act with fewer mistakes

It is especially opinionated around UI work, where most FiveM projects end up needing consistency, speed, and visual quality at the same time.

---

Quick Start

1. Install

npm install

2. Build

npm run build

3. Point the MCP host to the compiled server

This project runs as a local stdio MCP server.

Use:

• command: node
• args: ["./dist/index.js"] in repo-local configs, or ["${workspaceFolder}/dist/index.js"] in hosts that support workspace interpolation
• env.FIVEM_MCP_ALLOWED_DIRS: the resource folders the server is allowed to read/write

Example allowed dirs:

D:\FiveM\server-data\resources
D:\FiveM\server-data\resources\[local]

If you want more than one root, separate them with ;.

D:\FiveM\server-data\resources;D:\FiveM\server-data\resources\[local]

---

First-Time User Layer

If you are new to MCP or new to this repo, this is the minimum you need to understand:

1. Your IDE starts this server locally through stdio.
2. The server exposes tools, resources, and prompts.
3. The agent can then inspect, scaffold, and edit FiveM resources for you.
4. File access is intentionally restricted to the directories declared in FIVEM_MCP_ALLOWED_DIRS.

What it is good at

• FiveM resource scaffolding
• NUI bootstrap and visual template generation
• safe local file reads/writes
• line-based edits for more controlled patching
• quick starting points for dashboards, HUDs, inventories, and modal UIs

What it is not trying to be

• a hosted multi-user MCP platform
• a generic backend automation server
• a remote HTTP MCP service

This repo is optimized for local dev flow, especially for AI IDEs working directly on a FiveM codebase.

---

Template System

This project currently ships with UI variants and visual themes so new resources can start from something that already feels intentional.

UI Variants

Variant	Best for
modal	menus, shops, dialogues, forms
hud	status bars, needs, overlay widgets
inventory	slot grids, item panels, loot/shop layouts
dashboard	tablets, admin panels, dispatcher/ops interfaces

UI Themes

Theme	Visual direction
violet	futuristic, flexible, general-purpose
police	institutional, tactical, cold
amber	commerce, crafting, marketplace, garage
emerald	clean ops, admin, support, health-style flows

Example idea combinations

• dashboard + police for a police tablet
• inventory + amber for a premium garage/shop
• hud + emerald for clean status overlays
• modal + violet for general roleplay menus

---

Tooling Layer

Filesystem Tools

Tool	Purpose
fs.list	list directories inside allowed roots
fs.read_text	read text files with SHA256
fs.write_text	write text files with optional hash validation
fs.edit_lines	apply line-range edits
fs.mkdirp	create directories recursively

FiveM Tools

Tool	Purpose
fivem.resource_create	create a new FiveM resource with optional UI
fivem.resource_inspect	inspect fxmanifest.lua basics
fivem.ui_add	attach NUI scaffolding to an existing resource
fivem.framework_detect	infer standalone, qb-core, or esx
fivem.resource_audit	audit resource/NUI structure
fivem.ui_scaffold	generate or replace the UI bundle

MCP Resources

Resource	Purpose
fivem://docs/core-notes	core FiveM + NUI reminders
fivem://docs/ui-patterns	quick UI variant/theme guidance

MCP Prompts

Prompt	Purpose
fivem-ui-task	guide an agent toward the right template and visual direction

---

Stack

Layer	Choice
Language	TypeScript
Runtime	Node.js
MCP SDK	@modelcontextprotocol/sdk
Validation	zod
Transport	stdio
Build	tsc
Dev runner	tsx

Project scripts:

npm run dev
npm run build
npm run start

---

For Repository Scanners

The block below is intentionally compact and machine-friendly.

name: fivem-mcp
category: model-context-protocol-server
domain: fivem
focus:
  - fivem-resource-scaffolding
  - nui-ui-templates
  - safe-local-filesystem-edits
transport: stdio
runtime: node
language: typescript
entrypoint: dist/index.js
source_entrypoint: src/index.ts
capabilities:
  tools: true
  resources: true
  prompts: true
hosts:
  - cursor
  - trae
  - claude-desktop
framework_detection:
  - standalone
  - qb-core
  - esx
ui_variants:
  - modal
  - hud
  - inventory
  - dashboard
ui_themes:
  - violet
  - police
  - amber
  - emerald
env:
  required:
    - FIVEM_MCP_ALLOWED_DIRS
license: MIT
author: Luan Silva
studio: Tekton

---

Project Structure

FivemMcp/
├─ src/
│  ├─ index.ts
│  ├─ fivem-tools.ts
│  ├─ fs-tools.ts
│  ├─ security.ts
│  └─ templates.ts
├─ dist/
├─ package.json
├─ tsconfig.json
└─ README.md

Source map

• src/index.ts: MCP server registration
• src/fivem-tools.ts: FiveM-oriented actions
• src/fs-tools.ts: safe file operations
• src/security.ts: directory boundary enforcement
• src/templates.ts: UI variants and themes

---

Add to Cursor

You can add this server either globally or per project.

Suggested project config

Create:

.cursor/mcp.json

{
  "mcpServers": {
    "fivem-mcp": {
      "command": "node",
      "args": [
        "${workspaceFolder}/dist/index.js"
      ],
      "env": {
        "FIVEM_MCP_ALLOWED_DIRS": "D:\\FiveM\\server-data\\resources;D:\\FiveM\\server-data\\resources\\[local]"
      }
    }
  }
}

Good to know

• Cursor also supports a global mcp.json.
• If Cursor does not detect the server immediately, reload MCP from Settings.
• Using ${workspaceFolder}/dist/index.js keeps the config portable across machines.

---

Add to Trae

Prefer a project-level config so the server path stays relative to the repo instead of pointing to one machine.

Create:

.trae/mcp.json

Suggested config

{
  "mcpServers": {
    "fivem-mcp": {
      "command": "node",
      "args": [
        "./dist/index.js"
      ],
      "env": {
        "FIVEM_MCP_ALLOWED_DIRS": "D:\\FiveM\\server-data\\resources;D:\\FiveM\\server-data\\resources\\[local]",
        "START_MCP_TIMEOUT_MS": "60000",
        "RUN_MCP_TIMEOUT_MS": "60000"
      }
    }
  }
}

Notes

• In Trae, command should be a clean executable name or full executable path.
• Put file paths in args, not inside command.
• For portability, keep the config inside the repo and keep args relative to the repo build output.

---

Add to Claude

For a repo-portable setup, prefer Claude Code with a project-level .mcp.json.

Create:

.mcp.json

{
  "mcpServers": {
    "fivem-mcp": {
      "command": "node",
      "args": [
        "./dist/index.js"
      ],
      "env": {
        "FIVEM_MCP_ALLOWED_DIRS": "D:\\FiveM\\server-data\\resources;D:\\FiveM\\server-data\\resources\\[local]"
      }
    }
  }
}

Why this version is preferred

• it lives inside the repo
• it does not leak one developer's machine path
• it stays portable when the repository moves

Claude Desktop note

Claude Desktop uses a global config file, so repo-relative paths are not as clean there. If you must use Desktop, prefer a tiny launcher or env-based wrapper instead of hardcoding one developer's home directory into docs or committed config.

---

Example Calls

Create a new resource

{
  "tool": "fivem.resource_create",
  "arguments": {
    "resourceName": "police-tablet",
    "withUi": true,
    "framework": "qb-core",
    "uiVariant": "dashboard",
    "uiTheme": "police",
    "title": "Police Operations"
  }
}

Scaffold a UI into an existing resource

{
  "tool": "fivem.ui_scaffold",
  "arguments": {
    "resourceDir": "garage-ui",
    "uiVariant": "inventory",
    "uiTheme": "amber",
    "overwrite": true,
    "title": "Premium Garage"
  }
}

Audit a resource

{
  "tool": "fivem.resource_audit",
  "arguments": {
    "resourceDir": "police-tablet"
  }
}

---

Security Model

This server does not expose unrestricted filesystem access.

It resolves all user-supplied paths against the directories listed in:

FIVEM_MCP_ALLOWED_DIRS

That means:

• no arbitrary disk traversal by default
• no writes outside approved FiveM roots
• safer agent behavior when multiple resources exist on the same machine

If you want broader access, expand the allowed roots deliberately.

---

Development

Run in dev mode

npm run dev

Build for IDE use

npm run build

Run the compiled server

node dist/index.js

---

Roadmap Direction

This repo is already useful as a local FiveM MCP server, but its natural evolution is clear:

• stronger template catalog for real FiveM products
• richer UI families like banking, garage, MDT/tablet, dispatch, shops
• more polished visual systems around the current variant/theme model
• tighter onboarding for teams adopting MCP in game scripting workflows

---

License

This project is open source under the MIT License.

Produced by Luan Silva at Tekton.

---

Credits

Created for builders who want AI assistance to feel native inside a FiveM workflow, not bolted on after the fact.