FiveM MCP

fivem-mcp

一个 MCP（Model Context Protocol）服务，可让 AI Agent（Claude、Qwen 或任何支持 MCP 的程序）在同一台机器上 构建、运行和实时测试 FiveM 服务。

它补上了“在游戏中到底能不能正常运行？”这一问题所缺失的测试环节：Agent 可以运行真实的控制台命令，同时监视服务日志和正在运行的 FiveM 客户端的实时 F8 控制台，等待指定输出并作出响应，而无需你操作键盘。

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

状态

v0.5 可驱动整个工作流程：服务控制台（RCON）、客户端 F8 控制台（devcon）、游戏窗口（启动、聚焦、截图、键盘/鼠标）以及用于 natives、exports 和 NUI 回调的游戏内桥接（mcpb），还有现成的测试提示词。工具会返回结构化内容，携带 MCP 注释，并在客户端取消时立即停止。所有功能均已在真实的 FXServer 和 FiveM Legacy 客户端上完成实时验证（参见 docs/plan.md 和 scripts/live-*.mjs）。

发布渠道

渠道	地址
npm	fivem-mcp-server — npx -y fivem-mcp-server
MCP Registry	io.github.ziyacivan/fivem-mcp（registry.modelcontextprotocol.io）
源码发布版本	GitHub Releases，标签为 vX.Y.Z

仓库的 GitHub Packages 侧边栏特意留空：该软件包发布在 npmjs.com，而非 GitHub Packages；后者会强制使用带作用域的 @ziyacivan/ 软件包名称，还会多出一个毫无益处的注册表。

要求

• Node 22+（服务端可运行于 Windows、macOS 或 Linux；客户端 devcon 可在运行 FiveM 客户端的任何平台上工作。由于 devcon 默认绑定到 localhost，client_* 工具必须在该机器上运行）。
• 一个由你管理且正在运行的 FXServer（为 server_command 设置 rcon_password）。
• 使用客户端控制台工具需要 Legacy FiveM 客户端（Enhanced 已移除客户端 devcon 端口；参见 docs/protocol.md）。
• 键盘/鼠标/截图工具仅限 Windows，并且必须在运行游戏的机器上使用。在其他平台上，除这些工具外的所有工具都可正常提供服务。

安装

已发布到 npm，无需克隆。一行命令即可将其添加到 Claude Code：

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 表示在每个项目中均可用；省略该参数即可添加仅限当前项目的配置。使用 claude mcp get fivem 验证，状态应显示 ✓ Connected。使用 claude mcp remove fivem -s user 移除。）

若要使用共享项目配置，请在仓库根目录放入 .mcp.json 并提交。Claude Code 会在首次打开时请求批准，也可以通过 ${VAR} 展开，从本地不含 .env 的 shell 中插入环境变量值：

{
  "mcpServers": {
    "fivem": {
      "command": "npx",
      "args": ["-y", "fivem-mcp-server"],
      "env": {
        "FIVEM_RCON_PASSWORD": "${FIVEM_RCON_PASSWORD}",
        "FIVEM_SERVER_LOG": "${FIVEM_SERVER_LOG}"
      }
    }
  }
}

对于 Claude Desktop（或任何使用 JSON 配置的客户端），请添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "fivem": {
      "command": "npx",
      "args": ["-y", "fivem-mcp-server"],
      "env": { "FIVEM_RCON_PASSWORD": "your-rcon-password" }
    }
  }
}

该服务也已在 MCP Registry 中列出，名称为 io.github.ziyacivan/fivem-mcp。从源码构建（开发）：

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

配置（环境变量）

变量	默认值	含义
FIVEM_HOST	127.0.0.1	运行 FiveM 客户端的机器（devcon 主机）
FIVEM_EXECUTABLE	%LOCALAPPDATA%\FiveM\FiveM.exe	launch 工具使用的 FiveM.exe
FIVEM_CLIENT_DEVCON_PORT	29200 then 29300	覆盖客户端 devcon 端口
FIVEM_RCON_ADDRESS	FIVEM_HOST:30120	FXServer 游戏端口（UDP RCON + getinfo）
FIVEM_RCON_PASSWORD	—	与 server.cfg 中的 rcon_password 一致；server_command 需要此密码
FIVEM_SERVER_LOG	—	FXServer 重定向标准输出的路径；启用服务端 read_console / wait_for_console。自 v0.5 起，桥接不需要此项（结果通过带内方式轮询）——它是 v0.5 之前的备用传输方式
FIVEM_MCPB_TOKEN	—	与服务端上的 mcpb_token 一致；每次桥接请求都会携带此令牌
FIVEM_CONSOLE_CAPACITY	5000	环形缓冲区中保留的客户端控制台行数
FIVEM_QUIET_MS	400	命令输出在静默此时长后视为完成
FIVEM_COMMAND_TIMEOUT_MS	5000	client_command 输出的默认最长等待时间
FIVEM_MCP_DEBUG	—	设为 1 时，将 devcon 帧和 RCON 往返记录到 stderr

工具

工具	功能
status	连接状态：RCON、日志文件、客户端 devcon。请先调用。
server_info	通过 UDP 执行 getinfo——主机名、玩家数、最大客户端数、协议、游戏版本。无需凭据。
server_command	通过 UDP RCON 执行任意服务端控制台命令；返回捕获的输出。
client_command	通过 devcon 在运行中的 Legacy 客户端 F8 控制台中输入命令（不会抢占焦点）。这是本地控制台命令层——connect、quit、工具命令；RegisterCommand 聊天命令属于不同系统（请使用具有控制台权限运行的 server_command，或输入/桥接工具）。返回其打印的控制台行。
read_console	最近的行：客户端 = 实时 devcon 流（支持 afterSeq 分页），服务端 = FIVEM_SERVER_LOG 的末尾内容。可按 channel / contains / pattern 筛选。
wait_for_console	阻塞等待符合正则表达式的行出现——这是你的断言原语。
list_commands	客户端控制台已知的所有命令（devcon 握手）。
launch	启动 FiveM，可选择直接连接到 host:port（默认为已配置的服务端）。
quit_game	通过 devcon 正常执行 quit；force 会终止 FiveM 进程树。
window_status	游戏窗口是否存在、标题、pid、rect、前台状态。
focus_window / restore_focus	将游戏窗口置于前台 / 将焦点还给你的窗口。输入工具会自动获取焦点。
screenshot	游戏窗口的 PNG 图像（PrintWindow，屏幕 BitBlt 作为后备）。图像会缩小——默认尺寸为 900，可选 crop 矩形区域。整个会话中每张截图都会消耗对话记录令牌：优先使用文本探测，截图区域尽量小。
press_key / hold_key / release_key	真实扫描码输入——GTA 的 DirectInput 会忽略仅通过 VK 注入的输入。进程退出时会释放按住的键。
type_text	字面 Unicode 事件——F8 控制台和聊天 NUI 读取的输入通道。
mouse_move / click / scroll	相对移动用于控制摄像机；绝对坐标用于将光标定位到 NUI。
wait	在操作之间暂停（加载画面、行走循环）。
read_client_log	FiveM 安装目录中最新的 CitizenFX_log_*.log。
bridge	调用 mcpb 桥接资源：ping、players、poll、call_export、trigger_event（服务端部分），以及 ping、position、teleport、freeze、call_native、send_nui、nui_callback（客户端部分）。op 会根据所选目标进行验证。

提示词

此项目随附了两个 MCP 提示词，提炼自经过实时验证的循环流程：

• test_resource(resource, expectations?) — 干净重启 → 扫描控制台错误 → 扫描客户端一侧 → 游戏内场景（按键、截图、桥接状态）→ 提供证据支持的 PASS/FAIL 报告；任何无法验证的内容都会明确说明。
• smoke_check — 快速全面检查：连接、所用服务端、两侧的错误日志尾部、 窗口和截图、持久化客户端日志。每项标记为 OK/WARN/DOWN。

桥接资源（bridge/）

客户端侧测试（原生函数、NUI 回调、位置）超出了 devcon 和 RCON 的能力范围；这个小型配套资源填补了这一空白，并随本仓库一同提供。

# 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

并使用 FIVEM_MCPB_TOKEN 将此服务指向该资源。然后：

bridge { target: "client", src: 1, op: "position" }
bridge { target: "server", op: "call_export", args: "{\"resource\":\"myres\",\"method\":\"money\",\"args\":[1]}" }

客户端结果会通过带内队列返回，并通过 RCON 轮询（自 v0.5 起，粒度约为 100 ms；无需日志文件；v0.5 之前的资源仍会回退到读取日志尾部）。

仅限开发服务端。 mcpb_enabled 默认为 false，此命令仅接受来自控制台/RCON 的调用（绝不接受玩家调用），设置令牌时也会进行检查——但 call_native 的安全性完全取决于其背后的控制台。请勿在任何重要环境中启用 RCON 和此桥接资源；参见 SECURITY.md。完整的线路协议约定见：docs/protocol.md §4。

典型循环流程（Agent 的操作）

1. server_command: "ensure my-resource"
2. wait_for_console: target=server, pattern="Started resource my-resource|Error"
3. client_command: "connect localhost:30120" 会执行连接操作，然后 read_console: target=client 会捕获未进入服务端日志的客户端控制台输出。

安全说明——暴露任何内容前请阅读

• **客户端 devcon 套接字没有身份验证。**任何能够访问它的人都能在该游戏客户端中运行本地控制台命令（connect、quit 等）。除非客户端以 -devcon 启动（此时会绑定到 0.0.0.0），否则 FiveM 会将其绑定到 127.0.0.1；此工具依赖默认的环回地址，绝不需要其他地址。不要通过隧道转发它。
• **RCON 是服务端的管理员根权限。**请设置强密码 rcon_password；FIVEM_RCON_PASSWORD 存储在 MCP 配置中——请以同等方式保护该文件。
• 当前版本的 FXServer 本身没有服务端 devcon 套接字（已于 2026-09-02 验证），因此服务端一侧使用 RCON + 日志尾部读取。
• 只要 Agent 能执行任何 exec 命令，就应视为 server_command 会赋予其你设备上的 root 权限；仅对开发服务端运行。

开发

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)

发布：将 Unreleased 下的变更日志说明移至新版本标题下，然后运行 pnpm version <patch|minor|major>（会更新并同步 server.json 和桥接清单，并创建标签），在你的计算机上运行 npm publish（prepublishOnly 会运行完整门禁），然后运行 git push --follow-tags。随后 Release 工作流会重新运行门禁、根据 CHANGELOG.md 创建 GitHub Release，并向 MCP Registry 注册此版本。 参见 CONTRIBUTING.md。

针对真实服务端/游戏进行实时验证：pnpm live:probe、live:e2e、live:m2、live:m3。

线路协议（DevCon 帧、RCON/getinfo OOB 数据报、Cfx 字符串哈希）在 docs/protocol.md 中逐字节说明，内容根据开源的 CitizenFX 服务端 citizenfx/fivem@03dcc562 整理。已通过实时验证：RCON 回复格式、getinfo 响应以及大于 8 字节的质询丢弃行为，均于 2026-09-02 在真实 FXServer 上确认。

许可证

MIT。FiveM/CitizenFX 名称是 Cfx.re 的商标；本项目与 Cfx.re 无关联，也未获其认可。