Unreal MCP

🚀 虛幻引擎MCP服務器

這是一個全面的模型上下文協議（MCP）服務器，它允許AI助手通過遠程控制API來控制虛幻引擎。該服務器使用TypeScript構建，專為遊戲開發自動化而設計。

🚀 快速開始

前提條件

• Node.js 18+
• 虛幻引擎 5.0 - 5.6
• 必需的UE插件（通過 編輯 ▸ 插件 啟用）：
  • 遠程控制API – 核心遠程控制HTTP/WS端點
  • 遠程控制Web界面 – 啟用此服務器使用的WebSocket橋接
  • Python編輯器腳本插件 – 為自動化暴露Python運行時
  • 編輯器腳本實用工具 – 解鎖工具中使用的編輯器Actor/資產子系統
  • Sequencer（內置） – 為電影工具保持啟用狀態
  • 關卡序列編輯器 – manage_sequence 操作必需

💡 使用建議

切換任何插件後，重啟編輯器以完成激活。在連接之前，請保持 編輯器腳本實用工具 和 Python編輯器腳本插件 啟用，否則許多基於子系統的工具（如Actor生成、音頻、植被、UI小部件）出於安全考慮將拒絕運行。

插件功能映射

安裝

選項1：NPM包（推薦）

# 全局安裝
npm install -g unreal-engine-mcp-server

# 或在項目中本地安裝
npm install unreal-engine-mcp-server

選項2：克隆並構建

# 克隆倉庫
git clone https://github.com/ChiR24/Unreal_mcp.git
cd Unreal_mcp

# 安裝依賴並構建
npm install
npm run build

# 直接運行
node dist/cli.js

虛幻引擎配置

將以下內容添加到項目的 Config/DefaultEngine.ini 文件中：

[/Script/PythonScriptPlugin.PythonScriptPluginSettings]
bRemoteExecution=True
bAllowRemotePythonExecution=True

[/Script/RemoteControl.RemoteControlSettings]
bAllowRemoteExecutionOfConsoleCommands=True
bEnableRemoteExecution=True
bAllowPythonExecution=True

然後在：編輯 > 項目設置 > 插件 > 遠程控制 中啟用Python執行。

📦 MCP客戶端配置

Claude桌面版 / Cursor

對於NPM安裝（本地）

{
  "mcpServers": {
    "unreal-engine": {
      "command": "npx",
      "args": ["unreal-engine-mcp-server"],
      "env": {
        "UE_HOST": "127.0.0.1",
        "UE_RC_HTTP_PORT": "30010",
        "UE_RC_WS_PORT": "30020",
        "UE_PROJECT_PATH": "C:/Users/YourName/Documents/Unreal Projects/YourProject"
      }
    }
  }
}

對於克隆/構建安裝

{
  "mcpServers": {
    "unreal-engine": {
      "command": "node",
      "args": ["path/to/Unreal_mcp/dist/cli.js"],
      "env": {
        "UE_HOST": "127.0.0.1",
        "UE_RC_HTTP_PORT": "30010",
        "UE_RC_WS_PORT": "30020",
        "UE_PROJECT_PATH": "C:/Users/YourName/Documents/Unreal Projects/YourProject"
      }
    }
  }
}

✨ 主要特性

核心功能

• 資產管理 - 瀏覽、導入和創建材質
• Actor控制 - 生成、刪除和操作帶有物理效果的Actor
• 編輯器控制 - PIE會話、相機和視口管理
• 關卡管理 - 加載/保存關卡、燈光和環境構建
• 動畫與物理 - 藍圖、狀態機、布娃娃、約束
• 視覺效果 - Niagara粒子、GPU模擬、程序效果
• Sequencer - 電影製作、相機動畫和時間軸控制
• 控制檯命令 - 安全執行，過濾危險命令

📄 可用工具（13個）

🔧 關鍵特性

• 優雅降級 - 即使沒有與UE連接，服務器也能啟動
• 自動重連 - 每10秒嘗試重新連接
• 連接超時 - 5秒超時，可配置重試次數
• 非侵入式健康檢查 - 每30秒使用回顯命令
• 命令安全 - 阻止危險的控制檯命令
• 輸入靈活性 - 向量/旋轉器接受對象或數組格式
• 資產緩存 - 10秒TTL以提高性能

📚 支持的資產類型

藍圖、材質、紋理、靜態/骨骼網格體、關卡、聲音、粒子、Niagara系統

💻 示例控制檯命令

基礎用法

• 統計信息 - stat fps、stat gpu、stat memory
• 視圖模式 - viewmode wireframe、viewmode unlit
• 遊戲玩法 - slomo 0.5、god、fly
• 渲染 - r.screenpercentage 50、r.vsync 0

📋 配置

環境變量

UE_HOST=127.0.0.1              # 虛幻引擎主機
UE_RC_HTTP_PORT=30010          # 遠程控制HTTP端口
UE_RC_WS_PORT=30020            # 遠程控制WebSocket端口
UE_PROJECT_PATH="C:/Users/YourName/Documents/Unreal Projects/YourProject"  # .uproject文件的絕對路徑
LOG_LEVEL=info                 # debug | info | warn | error

Docker

docker build -t unreal-mcp .
docker run -it --rm unreal-mcp

從Docker Hub拉取

docker pull mcp/server/unreal-engine-mcp-server:latest
docker run --rm -it mcp/server/unreal-engine-mcp-server:latest

🛠️ 開發

npm run build          # 構建TypeScript
npm run lint           # 運行ESLint
npm run lint:fix       # 修復linting問題

🤝 貢獻

歡迎貢獻代碼！請遵循以下規則：

• 包含重現問題的步驟
• 保持PR聚焦且規模較小
• 遵循現有的代碼風格

📄 許可證

本項目採用MIT許可證，請參閱 LICENSE 文件獲取詳細信息。