SimpleMcpServer

让 AI 代理（Claude Code、OpenCode 等）通过 MCP 协议直接操作 Unity 场景。
必须配合 SimpleMCPBridge（Unity 侧桥接包）使用。

架构

AI Agent (Claude Code / OpenCode)
    │  MCP (stdio)
    ▼
SimpleMcpServer (Node.js/TypeScript)   ← 本仓库
    │  WebSocket
    ▼
SimpleMCPBridge (C#)                   ← 另一个仓库，需单独 clone 到 Unity Assets/
    │
    ▼
Unity Editor / Runtime

• SimpleMcpServer（本仓库）— 处理 MCP 协议，注册工具，转发请求到 Unity

• SimpleMCPBridge（companion repo）— 在 Unity 内运行的 WebSocket 客户端，执行场景操作

除桥外，Server 也能作为 MCP 客户端 接入外部标准 MCP server（如 BlenderMCP）， 把它们的工具以 <前缀>.<工具名> 暴露给 AI（如 blender.get_scene_info），见「外部 MCP 适配器」。

Related MCP server: Agent Bridge for Unity

前置条件

• Node.js 22+

• Unity 2022.3+ — 项目已安装 SimpleMCPBridge 包

• npm — 随 Node.js 一起安装

验证 Node.js：

node --version   # 应输出 v22.x.x 或更高
npm --version    # 应输出 10.x.x 或更高

安装与设置

自动安装（推荐）

双击 setup.bat。

手动安装

cd SimpleMcpServer
npm install
npm run build

使用

前置：安装 SimpleMCPBridge

cd YourUnityProject/Assets/
git clone https://github.com/redcool/SimpleMCPBridge_Unity.git SimpleMCPBridge

1. 启动 Unity Bridge（prefab 方式）

1. 用 Unity 打开项目

2. 将 Assets/SimpleMCPBridge/Prefabs/MCPBridge.prefab 拖入场景（或给任意 GameObject 添加 MCPBridge 组件）

3. 选中该对象，Inspector 顶部即显示连接状态（● Connected / ○ Disconnected）、ws://ip:port、Bridge ID 与 Connect / Disconnect 按钮

4. Server IP / Port 默认 127.0.0.1:45678，如需修改见下方 bridge-config.json

Bridge 通过 [ExecuteAlways] 在 Edit Mode、Play Mode、打包运行三态下均工作；默认 isAutoReconnect=true，场景加载、进出 Play Mode、脚本重编译（domain reload）后自动重连，无需手动操作。

bridge-config.json（可选，默认即可用）

Bridge 启动时自动加载配置——配置文件不存在时，首次自动从包内 Resources/bridge-config.json 拷贝生成（已存在则不覆盖），改完需重启生效：

{ "serverIp": "127.0.0.1", "serverPort": 45678, "encryptionKey": "" }

• serverIp/serverPort — 与 Server 侧 config.json 的 ip/port 对应

• encryptionKey — 与 Server 侧 encryptionKey 一致时启用 AES-256-CBC 载荷加密；空 = 透传

• methodBlocklist / methodAllowlist（可选）— scene.call_component_method 权限控制，详见桥 README

2. 启动 MCP Server

推荐：在独立 cmd 窗口运行（不占用 AI 工具的终端）

# 在 PowerShell 或 cmd 中执行：
Start-Process -FilePath "cmd.exe" -ArgumentList "/K", "cd /d path\to\SimpleMcpServer && start.bat"

或者在文件管理器双击 start.bat 也会弹出 cmd 窗口。

# 编译 + 启动（直接在当前终端）
start.bat

# 跳过编译（代码未改时）
start-quick.bat

连接成功输出：

[Server] Bridge connected
[Server] Registered N tool(s) from bridge [ID: xxxx]
[Server] Ready (ws://127.0.0.1:45678)

3. 配置 AI 代理

{
  "mcpServers": {
    "unity": {
      "command": "node",
      "args": ["path/to/SimpleMcpServer/dist/index.js"]
    }
  }
}

支持的传输端点

AI 代理若走网络连接本 Server（非 stdio），url 填 http://<host>:45678/mcp-stream（推荐）或 /sse。

4. 验证连通性

node tests/test-e2e.cjs

预期输出：*** TEST PASSED ***

对象寻址

Unity 侧的场景工具同时支持两种方式定位 GameObject：

解析优先级：instanceId > path。get_hierarchy 和 get_objects 的返回值同时包含两者。

外部 MCP 适配器（plan C：接入社区 MCP server）

除了直连自家桥（WebSocket wire protocol），Server 还能作为 MCP 客户端 对接外部标准 MCP server，把它们的工具以 <toolsPrefix>.<工具名> 暴露给 AI。社区生态（BlenderMCP、UE MCP 等）无需重写桥即可接入，且与桥工具并存（/rpc 与 /mcp 均可用）。

配置（config.json 的 mcpServers 段，改后重启生效）：

"mcpServers": [
  { "name": "blender", "command": "uvx", "args": ["blender-mcp@1.9.1"], "toolsPrefix": "blender" }
]

mcpServers 条目字段：

• command / args — 以 stdio 启动外部 MCP server（推荐 pin 具体版本，防上游漂移）

• 生命周期：服务器启动时 spawn 并 tools/list 拉取工具表；子进程退出后按 10s→30s→60s→120s 指数退避自动重连（外部应用如 Blender 重启后无需重启本 Server）

• 工具名冲突时 adapter 优先（先于桥工具合并）

• 危险工具门：名字以 .execute_* 结尾的任意代码执行类工具（如 blender.execute_blender_code）与内置 editor.eval 同策略——evalEnabled=false 时列表隐藏 + 调用拒绝

• MCP image 块返回（如视口截图）自动落盘到 mcp-media/ 并返回路径，不塞进文本

接入步骤（以 Blender 为例）

适配层对接的是社区 BlenderMCP（ahujasid/blender-mcp，v1.9.1 实测）。对外部用户来说：AI 客户端接本 Server（MCP），Server 接 Blender（经 blender-mcp），全程只需两步安装 + 配一行配置。

① Blender 侧——安装 MCP addon（一次性，需在本机装过 uvx/uv）

uvx blender-mcp install-addon    # 写入 %APPDATA%\Blender Foundation\Blender\<版本>\scripts\addons\

② Server 侧——config.json 配 mcpServers（本仓库已内置 config.json.template 示例）

"mcpServers": [
  { "name": "blender", "command": "uvx", "args": ["blender-mcp@1.9.1"], "toolsPrefix": "blender" }
]

版本一致性：addon 与 blender-mcp 的版本建议一致（协议握手 ADDON_PROTOCOL_VERSION 校验，不一致连接会失败）。

③ 启动 Blender 窗口实例：addon 的 Auto-Start Server 选项默认开启——在任何 Blender 窗口的偏好设置里启用一次 addon（保存偏好）后，该实例每次启动都会自动启用 addon 并自动起 socket（默认端口 9876）。如需全自动（首次启用也不用手点），可在 Blender 用户目录 scripts/startup/ 放一个 addon_utils.enable 的小脚本（团队环境做法见 AGENTS.md 相关记录）。本仓库提供了多实例启动脚本：

pwsh scripts\start-blender-instance.ps1 -Instance 1

④ 验证

# /rpc tools/list 应见 blender.* 工具
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"blender.get_scene_info","arguments":{"user_prompt":""}}}

链路（实测通过，2026-09）：AI → Server(adapter) → uvx blender-mcp(stdio) → TCP 9876 → Blender addon → bpy。实测全流程：建低多边形树（建模 → smart_project UV → 平滑 + Principled 材质 → 视口截图落盘 mcp-media/）可用。

多 Blender 实例（同时开多个窗口，各自独立控制）

原理：每个实例 = 独立 socket 端口 + 独立的 blender-mcp 进程（适配层本来就按 mcpServers 条目逐条 spawn）+ 独立工具前缀。端口分配：实例 N → 9875+N（实例1=9876，实例2=9877…）。

1. 起实例（脚本注入 BLENDER_MCP_PORT 环境变量；Blender 的 startup 脚本 blender_mcp_auto.py 据此用对应端口起 addon socket）：

pwsh scripts\start-blender-instance.ps1 -Instance 2        # 第 2 个窗口 → 端口 9877
pwsh scripts\start-blender-instance.ps1 -Instance 2 -BlendFile D:\proj\a.blend

2. config.json 每条实例加一条 mcpServers（env.BLENDER_PORT 与实例端口对应）：

"mcpServers": [
  { "name": "blender",  "command": "<uvx>", "args": ["blender-mcp@1.9.1"], "toolsPrefix": "blender" },
  { "name": "blender2", "command": "<uvx>", "args": ["blender-mcp@1.9.1"],
    "env": { "BLENDER_PORT": "9877" }, "toolsPrefix": "blender2" }
]

3. 重启 Server → tools/list 同时出现 blender.* 与 blender2.*，调用完全隔离（各自查/改的是对应窗口的场景）。

补充：同一实例内切换 .blend 工程不需要任何配置——socket 是进程级的，agent 看到的就是该窗口当前打开的工程。

安全须知（Blender 接入必读）

1. blender.execute_blender_code = 任意代码执行：可在 Blender 内运行任何 Python（含 os/文件/网络）。它受 evalEnabled 门控（config.json）：置 false 后该工具从列表消失且调用被拒。仅在可信环境开启。

2. addon socket 仅监听本机回环：BlenderMCPServer 默认 bind localhost:9876，不暴露局域网——不要改 host 为 0.0.0.0 或做端口转发，否则局域网内的 MCP 客户端可直连你的 Blender。

3. 遥测默认开启：BlenderMCP 的 Allow Telemetry 偏好默认勾选，收集 prompt/代码/截图/轨迹数据。关闭：Blender 偏好面板「MCP for Blender」取消勾选，或调用 blender.disable_telemetry 工具。

4. 供应链：blender-mcp 建议 pin 版本（示例已 pin @1.9.1），addon 同样按该版本安装，避免上游意外更新破坏行为。

5. 权限边界：AI 对 Blender 的操作 = Blender 进程所属用户的权限（可读写本机文件、调网络）。等同于把"本机 Python 执行权"交给 AI。

6. 退出接入：删掉/注释 mcpServers 块，或在条目内加 "enabled": false，重启 Server 即断开（不卸载 Blender 侧任何东西）。

7. 已知坑：Blender 中文界面下默认对象名是本地化的（如 primitive_cube_add 生成 "立方体" 而非 "Cube.001"），脚本建议显式 o.name=...；经 PowerShell 传中文参数需显式 UTF-8 编码。

高层模板工具（本仓库预置的 blender.* 快捷工具）

除透传的 blender-mcp 原生工具外，Server 内置一组高层 Blender 模板工具（建模/骨骼/动画/导出，无需 AI 写 bpy 脚本）：blender.rig.humanoid、blender.rig.auto_weights、blender.anim.loop、blender.anim.quadruped、blender.mesh.primitive、blender.mesh.boolean、blender.body.build（参数化四足/人形体块）、blender.scene.export。

完整用法、参数表与典型工作流（如"一句话生成会走的四足动物"）见 docs/blender-mcp-template-tools.md。所有模板工具均受 evalEnabled 门控，并接受通用参数 adapter 指定目标 Blender 实例。

可用工具

工具由 Unity Bridge 通过 register_tools 动态注册，数量随桥接平台/条件编译变化（当前 Editor 桥实测 127 个桥工具 + 服务端合成 2 个 = 129 个）。下表按类别简述常用工具；完整清单见 SimpleMCPBridge 仓库 README。

场景工具（SceneHandler）

资源工具（AssetHandler，仅 Editor）

录制工具（RecordingHandler）

保存位置：

• PC: 项目根目录 VideoRecord/（Assets 同级）

• Android/iOS: app 临时目录 {temporaryCachePath}/VideoRecord/

编辑器工具

PlayerPrefs 工具（PlayerPrefsHandler）

UI Toolkit 工具（UIToolkitHandler）

配置

编辑 config.json（不存在时首次启动自动从 config.json.template 复制生成，见「首次运行」）。完整字段：

{
    "ip": "0.0.0.0",
    "port": 45678,
    "encryptionKey": "",
    "encryption": false,
    "evalEnabled": true,
    "allowedIps": ["127.0.0.1", "::1"],
    "llm": { "enabled": true, "provider": "agnes", "baseUrl": "https://apihub.agnes-ai.com/v1", "apiKey": "YOUR_API_KEY_HERE", "model": "agnes-2.0-flash", "temperature": 0.7, "maxTokens": 1024 },
    "webSearch": {
        "order": ["serper", "google", "bing", "ddg-html", "ddg-lite"],
        "region": "zh-CN",
        "serper": { "apiKey": "" },
        "google": { "apiKey": "", "cx": "" },
        "providerTimeoutMs": 15000,
        "cooldownMs": 60000
    }
}

• ip/port：监听地址与端口。本地 127.0.0.1，云端 0.0.0.0

• encryption/encryptionKey：可选 AES-256-CBC 载荷加密（替代 TLS/wss），Server 与 Bridge 配置需一致；空密钥 = 透传

• evalEnabled：editor.eval 工具开关（默认 true，以用户方便为先 —— 开发调试/快速原型/补救缺口工具时即时可用）。false 时 tools/list 不暴露 editor.eval 给 agent。风险：eval 执行任意 C# = 完全机器控制，任何能调 /rpc 的 AI 可执行任意代码（读写文件、删资产、网络访问）；不可信环境（共享机器/公网暴露）务必关闭或扩 allowedIps 白名单。Editor 侧另有 EditorPrefs SimpleMCPBridge_EvalEnabled 二次 gate，见桥 README「Editor Eval 开关与安全说明」

• allowedIps：IP 白名单（本版本新增）——只放行白名单内的客户端访问 HTTP /rpc、/sse、/mcp 端点、WebSocket / 桥接通道以及 /ab 资产端点，其余连接返回 403（WS）或 404（HTTP）；默认 ["127.0.0.1","::1"] 仅本机。配置缺失时自动从 config.json.template 复制生成 config.json（首次启动自动创建，见「首次运行」）；字段缺失/为空数组/非数组时回退到默认 ["127.0.0.1","::1"]（仅本机）

• llm：LLM 配置（apiKey 用环境变量 LLM_API_KEY 覆盖更安全；config.json 已被 .gitignore 排除，勿提交真实 key）

• webSearch：web.search 工具的多引擎配置（改动后重启生效）

  • order：引擎优先级（默认 serper → google → bing → ddg-html → ddg-lite），按序尝试，失败自动降级；未配置凭据的引擎自动跳过

  • region：中文查询的语言区域（默认 zh-CN），Serper/Google/必应/DDG 会带上对应 gl/hl、mkt、kl 参数，显著改善中文搜索质量

  • serper：可选（推荐）——填 apiKey（Serper.dev，Google 搜索结果 API，免费约 2500 次/月、免信用卡、需 Google 可达的网络——公司网络可用）即可启用。服务器启动时会探测 google.serper.dev 可达性——大陆网络（Google 不可达）自动回退 Bing/DDG，无需改配置；成功率/延迟最佳，中文质量 = Google

  • google：可选——Programmable Search JSON API（对新用户已关闭，仅老 key 可在 2027-01-01 前使用），留空自动跳过

  • providerTimeoutMs：单引擎请求超时（默认 15s；Serper/Google 探测用其中最多 5s）

  • cooldownMs：某引擎连续失败 ≥2 次后的冷却时间（默认 60s；防止被墙引擎每次拖慢所有搜索）

开发

npm run dev           # tsx 监听模式
node tests/test-e2e.cjs  # E2E 测试

# 目录结构
src/
├── index.ts           # 入口（启动 server）
├── server.ts          # WS Server + MCP handlers（核心）
├── bridgeState.ts     # bridge 连接状态/路由（last-registration-wins、failover）
├── ab.ts              # AssetBundle 上传/部署端点
├── crypto.ts          # AES-256-CBC 载荷加密（#ENC# 前缀）
├── config.ts          # config.json 加载（缺失时从 template 生成）
├── llm.ts             # LLM 代理（ai_request/ai_response）
├── logger.ts          # 日志（stderr + server.log，脱敏）
├── tools.ts           # 服务端合成工具（bridge.list / bridge.call）
└── types.ts           # 类型定义
tests/
├── test-e2e.cjs           # E2E 测试（initialize + tools/list + get_hierarchy）
├── test-playmode-cycle.cjs # Play Mode 循环测试（进出播放验证 bridge 自动重连）
└── auto-test-android.ps1  # Android 全流程自动化测试

故障排查

"WebSocket server error: listen EADDRINUSE" → 端口被占用，杀掉残留进程：

Get-Process -Name "node" | Stop-Process -Force

"Unity not connected" → Unity 没打开，或 SimpleMCPBridge 没启动

Bridge 进出 Play Mode 后断连 → 确认 Unity 菜单 Edit → Project Settings → Editor → Enter Play Mode Settings 中 Reload Domain 已开启。Bridge 依赖 [InitializeOnLoad] 在 domain reload 后重新订阅 EditorApplication.update。如关闭 Domain Reload，Bridge 连接会在 Play Mode 期间保持，但退出后无法自动重连。

测试超时 → E2E 测试会启动自己的 Server 实例，Bridge 需要通过重试循环重连到新 Server

HTTP 调用返回 403 → 请求源 IP 不在 allowedIps 白名单。修改 config.json 的 allowedIps 加来源 IP 后重启服务端。

相关仓库

技术说明

• MCP SDK v1.x 低阶 API（setRequestHandler），不用 registerTool()（该 API 在 connect() 后抛出异常）

• WebSocket 通信（ws 库），IP/Port 来自 config.json

• 工具通过 register_tools 消息从 Bridge 动态注册到 Server，Bridge 重连后自动重新注册

• Unity Bridge 活动传输为 .NET ClientWebSocket（NetWebSocketClient 封装，BridgeClient.ConnectToServer() 创建）；旧版纯 TCP RFC 6455 实现（WebSocketClient）已标记 [Obsolete] 仅作参考

• Server 同时暴露 HTTP /rpc 端点用于程序化调用（E2E 测试使用）

• /health 端点返回 bridge 连接状态、工具列表、播放模式状态

• HTTP /rpc、/sse、/mcp 端点受 allowedIps 白名单 gate（403）；WebSocket 桥接通道（1008 Forbidden）与 /ab 端点同样受白名单控制

• 消息负载上限 4MB（maxPayload）

• 服务端每 ~30s ping、超时未 pong 判定失活并 terminate() 断连（isAlive 心跳）

• 日志脱敏：工具名 + 参数长度（不打印明文 payload），错误路径保留详情

• config.json 不存在时首次启动自动从 template 复制生成；改完配置重启生效

• 进程级安全网：uncaughtException / unhandledRejection handler 记日志后继续运行（不崩进程），防单个坏工具响应或未捕获 rejection 带走整个 relay（丢连接 + retryQueue + 在途调用）