Fivem Server Doctor

Local MCP server for Claude Desktop, Codex, and other MCP clients that answers one question:

Why is my FiveM server or resource broken?

fivem-server-doctor-mcp reads local txAdmin/FiveM files over stdio, scans server.cfg, resource folders, manifests, and recent logs, then returns ranked findings with exact evidence. It can propose narrow text-file fixes and can apply only generated low-risk fixes when writes are explicitly enabled.

Maintained by FiveMX. Sponsor link: fivemx.com.

What It Detects

• Missing resource folders referenced by ensure or start.
• Resource folders missing fxmanifest.lua or __resource.lua.
• Common fxmanifest.lua problems: missing fx_version, missing game, missing listed files, missing dependencies.
• txAdmin/FiveM log patterns: missing resources, malformed manifests, missing dependency hints, port bind failures, missing license keys, database connection hints, yarn/webpack/module install errors.
• Secrets in output are masked, including license keys, DB URLs/passwords, tokens, and connection strings.

The scanner parses manifests as text. It never executes Lua from a resource.

Install

pnpm add -g fivem-server-doctor-mcp

Or run it without a global install:

npx -y fivem-server-doctor-mcp --server-cfg /path/to/server.cfg --resources /path/to/resources

CLI Options

fivem-server-doctor-mcp \
  --txdata /path/to/txData/default \
  --server-cfg /path/to/server.cfg \
  --resources /path/to/resources

Optional txAdmin status check:

TXHOST_API_TOKEN=... fivem-server-doctor-mcp \
  --txadmin-url http://127.0.0.1:40120 \
  --txadmin-token-env TXHOST_API_TOKEN

Writes are disabled by default. Enable generated low-risk patch application only for the launched process:

FIVEM_DOCTOR_ALLOW_WRITE=1 fivem-server-doctor-mcp --server-cfg ./server.cfg --resources ./resources

Codex Setup

codex mcp add fivem-doctor -- npx -y fivem-server-doctor-mcp \
  --server-cfg /path/to/server.cfg \
  --resources /path/to/resources \
  --txdata /path/to/txData/default

Then ask Codex:

Use fivem-doctor to run doctor_scan and explain why my FiveM server is not starting.

Claude Desktop Setup

Add this to your Claude Desktop MCP config:

{
  "mcpServers": {
    "fivem-doctor": {
      "command": "npx",
      "args": [
        "-y",
        "fivem-server-doctor-mcp",
        "--server-cfg",
        "/path/to/server.cfg",
        "--resources",
        "/path/to/resources",
        "--txdata",
        "/path/to/txData/default"
      ]
    }
  }
}

For write-enabled local patching, add an env block:

{
  "mcpServers": {
    "fivem-doctor": {
      "command": "npx",
      "args": ["-y", "fivem-server-doctor-mcp", "--server-cfg", "/path/to/server.cfg", "--resources", "/path/to/resources"],
      "env": {
        "FIVEM_DOCTOR_ALLOW_WRITE": "1"
      }
    }
  }
}

MCP Interface

Tools:

• doctor_scan: scans configured status, logs, server.cfg, resources, and manifests.
• resource_inspect: inspects one resource folder and manifest.
• propose_fixes: returns generated fix candidates.
• apply_fix: applies one generated fix only when writes are enabled, the target hash matches, the path is under configured roots, and the fix risk is low.

Resources:

• fivem://status
• fivem://server-cfg
• fivem://logs/recent
• fivem://resources
• fivem://resources/{name}/manifest

Prompts:

• diagnose_fivem_startup
• review_new_resource_install
• explain_txadmin_log_error

Safety Model

• No private txAdmin UI scraping.
• No browser sessions, cookies, or CSRF-protected routes.
• No RCON, restart, stop, ban, or live server control tools in v1.
• No arbitrary file writes.
• apply_fix only writes generated low-risk changes for server.cfg, fxmanifest.lua, or __resource.lua style text fixes under configured roots.
• Existing files are backed up into .fivem-doctor-backups/ before replacement.

Development

pnpm install
pnpm build
pnpm test

The test suite uses fixture-based node:test coverage and starts a real stdio MCP client against the built server.

Docs

• Fix FiveM resource not starting with Claude or Codex
• FiveM fxmanifest doctor
• txAdmin log analyzer MCP

License

MIT