FiveM服务器管理工具

mcp five-mcp服务器

FiveM RCON Model Context Protocol服务器

此基于TypeScript的MCP服务器提供FiveM插件开发调试和服务器管理功能：

• 通过RCON的FiveM服务器通信
• 管理插件（ensure、stop、restart）
• 监视服务器日志并获取插件日志
• 获取FiveM客户端日志
• 通过脚本执行F8控制台命令
• 通过事件系统进行服务器客户端间通信
• 与FiveM插件（mcp-bridge）合作
• 更新资源并检查服务器状态
• 执行任意RCON命令

MCP工具（v0.4.0）

MCP服务器版本： 0.4.0
mcp桥插件版本： 2.2.0

公共工具 13个 表示fivem_* 前缀）。

検证手顺： docs/verification.md

开发服务器先决条件

dev-local.cfg 例子：

setr mcp_bridge_enabled 1
setr mcp_bridge_allow_player_control 1
setr mcp_bridge_dev_only 1
setr mcp_bridge_include_tokens 0
ensure mcp-bridge
ensure screencapture

可选安全参数：

• mcp_bridge_command_allowlist
• mcp_bridge_command_denylist
• mcp_bridge_event_allowlist
• mcp_bridge_event_denylist

🚀 核心工具

1. fivem_plugin_manage -插件管理

集成管理插件的启动、停止、重新启动和资源更新

参数：

• action (必須):“确保”|“停止”|“重新启动”|“刷新”
• plugin_name （ensure/stop/restart时必需）：插件名称

使用例:

# プラグインの開始
fivem_plugin_manage --action ensure --plugin_name my-plugin

# プラグインの停止
fivem_plugin_manage --action stop --plugin_name my-plugin

# プラグインの再起動
fivem_plugin_manage --action restart --plugin_name my-plugin

# リソースの更新（fxmanifest変更後など）
fivem_plugin_manage --action refresh

2. fivem_command_execute -执行命令

整合服务器端和客户端的命令执行

参数：

• mode （必须）：“server”|“client”
• command （必需）：要执行的命令
• player_id （可选）：客户端模式下的目标玩家ID
• wait_for_result （可选）：在poll中等待客户端运行结果（默认值： true）

使用例:

# サーバー側でコマンド実行
fivem_command_execute --mode server --command "say Hello from Server!"

# 特定プレイヤーのクライアントでコマンド実行
fivem_command_execute --mode client --command "me waves hand" --player_id 1

# 全クライアントでコマンド実行
fivem_command_execute --mode client --command "engine"

3. fivem_rcon_execute -直接执行RCON命令

执行低级别服务器管理的直接RCON命令

参数：

• command （必需）：执行的RCON命令

使用例:

# 直接RCONコマンド実行（サーバー管理用）
fivem_rcon_execute --command "status"

# リソース管理
fivem_rcon_execute --command "restart my-plugin"

4. fivem_event_trigger -事件触发

整合服务器客户端之间的事件触发器

参数：

• type （必须）：“server”|“client”
• event_name （必需）：事件名称
• player_id （client时必须）：玩家ID
• args （可选）JSON编码参数（数组或对象）
• wait_for_ack （可选）：在poll中等待客户端事件的接收确认

使用例:

# サーバーイベントのトリガー
fivem_event_trigger --type server --event_name playerJoined --args '["player123", "NewPlayer"]'

# クライアントイベントのトリガー
fivem_event_trigger --type client --event_name showNotification --player_id 1 --args '["Hello Client!"]'

5. fivem_player_get -获取玩家信息

整合玩家一览获取和详细信息获取

参数：

• action （必须）：“list”|“info”
• player_id （info时必须）：玩家ID

使用例:

# プレイヤー一覧取得
fivem_player_get --action list

# 特定プレイヤーの詳細情報取得
fivem_player_get --action info --player_id 1

6. fivem_player_control -玩家操作（面向开发、QA）

集成电信、坐标获取、按键输入脉冲和截图

前提: 在开发服务器上 dev-local.cfg 由于 mcp-bridge / screencapture 已启动

参数：

• action （必须）： get_state | teleport | freeze | unfreeze | input_pulse | input_sequence | input_tap | screenshot | set_health | set_armor | give_weapon | set_heading | spawn_vehicle | enter_vehicle | repair_vehicle | look_at
• player_id （必需）：玩家ID
• coords （teleport时）： { x, y, z, heading? }
• input （输入脉冲/输入映射時): { keys: ["W","E"], duration_ms?: number }
• sequence （input_sequence时）： [{ keys, duration_ms, delay_ms? }]
• screenshot （screenshot时）： { quality?: 0.1-1.0 }

使用例:

fivem_player_control --action get_state --player_id 1
fivem_player_control --action teleport --player_id 1 --coords '{"x":100,"y":200,"z":30,"heading":90}'
fivem_player_control --action input_pulse --player_id 1 --input '{"keys":["W"],"duration_ms":2000}'
fivem_player_control --action screenshot --player_id 1 --screenshot '{"quality":0.6}'

7. fivem_logs_get -日志检索

整合服务器客户端插件日志捕获

参数：

• source (必須):“服务器”|“服务器插件”|“客户端”|“客户插件”
• lines （可选）：检索行数（默认值因源而异）
• plugin_name （可选）：插件名称（仅限*_plugin时）

使用例:

# サーバーログ取得
fivem_logs_get --source server --lines 100

# 特定プラグインのサーバーログ取得
fivem_logs_get --source server_plugin --plugin_name my-plugin --lines 50

# クライアントログ取得
fivem_logs_get --source client --lines 100

# 特定プラグインのクライアントログ取得
fivem_logs_get --source client_plugin --plugin_name my-plugin --lines 50

7. fivem_system_manage -系统管理

集成系统健康检查和日志清除

参数：

• action （必须）：“health”|“clear”

使用例:

# プラグインのヘルスチェック
fivem_system_manage --action health

# ログのクリア
fivem_system_manage --action clear

FiveM插件协作

专用的FiveM插件（mcp-bridge），提供RCON无法实现的高级功能：

🔗 协作体系结构

MCP Server ←→ RCON Protocol ←→ FiveM Server ←→ mcp-bridge Plugin

新方式的特点：

• ✅ 无需HTTP服务器
• ✅ 利用现有RCON连接
• ✅ 简单的实施
• ✅ 实时通信
• ✅ 轻巧、快速

🚀 通过插件提供的功能

• 服务器端命令执行：通过RCON自定义命令使用ExecuteCommand
• 客户端命令执行：特定玩家或所有玩家的命令执行
• 实时事件: TriggerEvent/TriggerClientEventの直接実行
• 玩家管理：获取在线玩家的详细信息
• 健康检查：监视插件状态

🆕 v0.3.0的新功能

• 客户端服务器隔离: fivem_command_execute在服务器和客户端之间明确分离
• 直接RCON実行: fivem_rcon_execute执行低级服务器管理命令
• 错误处理改善：通过优化ResponseParser，精确解析插件的响应
• 新RCON命令: mcp_client_command、mcp_client_command_all添加到插件

🔧 安装FiveM插件

1. fivem-plugin/mcp-bridge 将文件夹移到FiveM服务器的 resources 复制到目录
2. server.cfg 添加：

ensure mcp-bridge

3. 重新启动FiveM服务器

🎯 使用例

# サーバー側でメッセージ送信
fivem_command_execute --mode server --command "say Hello from MCP Bridge!"

# クライアント側でコマンド実行
fivem_command_execute --mode client --command "me waves" --player_id 1

# サーバーイベントのトリガー
fivem_event_trigger --type server --event_name playerJoined --args '["player123", "NewPlayer"]'

# プレイヤー情報の取得
fivem_player_get --action info --player_id 1

# プラグインの健康状態チェック
fivem_system_manage --action health

# 直接RCONコマンド実行
fivem_rcon_execute --command "status"

机能详细

资源

• fivem://logs/recent -最新服务器操作日志
• fivem://console/info -服务器控制台信息（通过日志文件）

工具

服务器管理

• fivem_plugin_manage -插件管理
• fivem_command_execute -执行命令（Server/Client）
• fivem_rcon_execute -直接执行RCON命令
• fivem_event_trigger -事件触发器
• fivem_player_get -获取玩家信息（List/Info）
• fivem_logs_get -日志检索（Server/Client/Plugin）
• fivem_system_manage -系统管理

开発

安装相关性：

npm install

服务器构建：

npm run build

开发时自动重建：

npm run watch

安装

光标IDE

要在Cursor IDE中使用，请添加设置：

1. 打开Cursor IDE设置（Cmd/Ctrl+，）
2. 在“MCP”中搜索
3. 添加以下设置：

{
  "mcp.servers": {
    "mcp-fivem": {
      "command": "/path/to/mcp-fivem/build/index.js",
      "env": {
        "RCON_ADDRESS": "localhost",
        "RCON_PORT": "30120",
        "RCON_PASSWORD": "your_rcon_password",
        "FIVEM_LOGS_DIR": "/path/to/your/fivem/txData/default/logs"
      }
    }
  }
}

或者，可以使用Cursor配置文件（settings.json），模板名称将采用不同的格式。

环境变数设定

通过设置以下环境变量，可以使用自动连接或默认值：

• RCON_ADDRESS：FiveM服务器主机（必需）
• RCON_PORT：RCON端口（必需）
• RCON_PASSWORD：RCON密码（必需）
• FIVEM_LOGS_DIR：存储服务器日志文件的目录路径（使用服务器日志功能时必需）
• FIVEM_CLIENT_LOGS_DIR：存储客户端日志文件的目录路径（使用客户端日志功能时必需）
• FIVEM_SCREENSHOTS_DIR：mcp-bridge的screenshot读取目的地（省略时为 FIVEM_MCP_BRIDGE_PATH/screenshots）
• FIVEM_MCP_SYNC_TARGET: npm run sync 部署到
• FIVEM_MCP_BRIDGE_PATH：mcp-bridge资源的基本路径

如果设置了所有环境变量，则在MCP服务器启动时自动尝试连接。

关于日志功能：

• fivem_logs_get --source server以及fivem_logs_get --source server_plugin单击功能区上FIVEM_LOGS_DIR中所述修改相应参数的值。
• fivem_logs_get --source client以及fivem_logs_get --source client_plugin单击功能区上FIVEM_CLIENT_LOGS_DIR中所述修改相应参数的值。

设置日志目录路径

服务器日志（FIVEM_LOGS_DIR）

FIVEM_LOGS_DIR包括服务器日志文件（fxserver.log、server.log等）直接存储的目录中所述修改相应参数的值。

设定例：

export FIVEM_LOGS_DIR="/path/to/server/txData/default/logs"

客户端日志（FIVEM_CLIENT_LOGS_DIR）

FIVEM_CLIENT_LOGS_DIR中描述的场景，使用下列步骤创建明细表，以便在概念设计中分析体量的周长CitizenFX.log等）直接存储的目录中所述修改相应参数的值。

设定例：

# Windows
export FIVEM_CLIENT_LOGS_DIR="C:\Users\username\AppData\Local\FiveM\FiveM.app\logs"

# Linux/WSL2
export FIVEM_CLIENT_LOGS_DIR="/home/username/.local/share/CitizenFX"

完全な环境变数设定例：

export RCON_ADDRESS="localhost"
export RCON_PORT="30120"
export RCON_PASSWORD="your_rcon_password"
export FIVEM_LOGS_DIR="/path/to/server/txData/default/logs"
export FIVEM_CLIENT_LOGS_DIR="/home/username/.local/share/CitizenFX"

目录结构示例：

# サーバーログ
/path/to/server/txData/default/logs/    ← FIVEM_LOGS_DIRで直接指定
├── fxserver.log                        ← メインログファイル
├── server.log                          ← サーバーログファイル
└── fxserver_20240101.log               ← 日付付きバックアップ

# クライアントログ
/home/username/.local/share/CitizenFX/  ← FIVEM_CLIENT_LOGS_DIRで直接指定
├── CitizenFX.log                       ← メインクライアントログ
├── CitizenFX_log.txt                   ← 追加ログファイル
└── launcher.log                        ← ランチャーログ

🚀 关于迁移

从旧工具迁移

现有的工具保持向后兼容性，但建议使用新的集成工具：

旧工具｜新工具｜更改点｜ |--------|--------|--------| | ensure_plugin | fivem_plugin_manage | action: "ensure" | | stop_plugin | fivem_plugin_manage | action: "stop" | | restart_plugin | fivem_plugin_manage | action: "restart" | | execute_command | fivem_rcon_execute 直接执行RCON命令 | execute_plugin_command | fivem_command_execute | mode: "server" | | trigger_server_event_plugin | fivem_event_trigger | type: "server" | | trigger_client_event_plugin | fivem_event_trigger | type: "client" | | get_players_plugin | fivem_player_get | action: "list" | | get_player_info_plugin | fivem_player_get | action: "info" | | get_fivem_server_logs | fivem_logs_get | source: "server" | | get_fivem_server_plugin_logs | fivem_logs_get | source: "server_plugin" | | get_fivem_client_logs | fivem_logs_get | source: "client" | | get_fivem_client_plugin_logs | fivem_logs_get | source: "client_plugin" |

| check_plugin_health | fivem_system_manage | action: "health" | | refresh_resources | fivem_plugin_manage | action: "refresh" | | clear_logs | fivem_system_manage | action: "clear" |

npm run inspector

检查器提供浏览器中访问调试工具的URL。

📝 変更履歴

v0.4.0

• 客户端命令执行现在支持异步结果轮询(wait_for_result)
• 客户端事件交付确认(wait_for_ack)via mcp_event_client_ack / mcp_async_poll
• 扩展玩家控制动作（健康/护甲/武器/车辆/外观）
• 安全门、审计日志、可选令牌编辑
• 文档/版本对齐和验证指南

v0.3.0（2025-07-06）

• 🆕 新机能：在服务器客户端之间添加命令执行功能
• 🆕 新工具: fivem_rcon_execute -直接执行RCON命令
• 🔧 改善: fivem_command_execute的mode: "server"/"client"更改为
• 🔧 改善：优化ResponseParser以改进错误处理
• 🔧 改善：在FiveM插件中mcp_client_command、mcp_client_command_all添加命令
• 📖 更新：全面更新文档和自述文件

v0.2.0版本

• 🆕 新机能：将17个工具集成到6个
• 🆕 新机能：统一的命名约定（fivem_*前缀）
• 🔧 改善：功能分组直观操作
• 🔧 改善：消除冗余，提高可维护性

v0.1.0

• 🎉 首次发布：基本FiveM RCON功能
• 🆕 新机能：插件管理、日志检索、事件系统