AI导哈

Unity编辑器MCP服务器

一个用于Unity编辑器集成的MCP服务器，支持AI助手通过标准化协议进行场景管理、游戏对象操作和脚本编辑等操作。

  • by Wally869
  • Rust
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Wally869/UnityMCP-rs

使用说明

Unity MCP服务器（Rust）

用于Unity编辑器集成的MCP（模型上下文协议）服务器，用Rust编写。

该服务器使AI助手（如Claude）能够通过标准化的MCP协议与Unity编辑器进行交互，允许场景管理、游戏对象操纵、脚本编辑等操作。

建筑

先决条件

  • Rust 1.70+（通过安装 生锈)
  • 在Windows上：使用C++工作负载的Visual Studio构建工具

构建命令

# Development build
cargo build

# Release build (optimized)
cargo build --release

# Run directly
cargo run -- --help

二进制文件将位于 target/debug/unity-mcp （或 target/release/unity-mcp 用于发布版本）。

用法

# Default: STDIO transport (for MCP client integration)
unity-mcp

# HTTP transport with WebSocket support
unity-mcp --transport http

# Custom HTTP port
unity-mcp --transport http --http-port 8090

# Target a specific Unity instance
unity-mcp --default-instance "MyProject@abc123"

# Enable debug logging
unity-mcp --log-level debug

命令行选项

选项 环境变量 默认值 描述
--transport UNITY_MCP_TRANSPORT stdio 运输方式： stdio 或 http
--http-url UNITY_MCP_HTTP_URL http://localhost:8080 HTTP服务器URL
--http-host UNITY_MCP_HTTP_HOST localhost HTTP服务器绑定主机
--http-port UNITY_MCP_HTTP_PORT 8080 HTTP服务器端口
--default-instance UNITY_MCP_DEFAULT_INSTANCE - 目标默认Unity实例
--log-level UNITY_MCP_LOG_LEVEL info 日志级别：跟踪、调试、信息、警告、错误
--pidfile - - 写入PID文件的路径
--skip-startup-connect UNITY_MCP_SKIP_STARTUP_CONNECT false 跳过初始Unity连接

Unity插件设置

此服务器与MCP for Unity插件配合使用，该插件必须安装在您的Unity项目中。

安装插件

  1. 复制 MCPForUnity 文件夹到Unity项目的 Assets 目录，或通过Unity包管理器安装
  2. 打开Unity并允许插件编译
  3. 插件将自动开始监听MCP服务器连接

插件配置

Unity插件通过WebSocket连接到MCP服务器。默认情况下，它预期：

  • Websocket URL: ws://localhost:8080/hub/plugin
  • Discovery的端口范围：6400-6500（TCP）

如果您在其他端口上运行服务器，请更新Unity中的插件设置：

  • 首选 窗口>Unity MCP>设置
  • 更新服务器URL以匹配您的配置

连接流程

  1. Unity插件启动并打开与MCP服务器的WebSocket连接
  2. 插件使用项目信息（名称、路径、哈希）注册自己
  3. MCP服务器现在可以通过此连接向Unity发送命令
  4. 命令在Unity中执行，响应被发回

建筑

┌─────────────────┐       WebSocket        ┌─────────────────┐
│   MCP Client    │◄─────────────────────►│   Unity MCP     │
│  (Claude, etc)  │                        │     Server      │
└─────────────────┘                        └────────┬────────┘
                                                    │
                                           WebSocket│/TCP
                                                    │
                                           ┌────────▼────────┐
                                           │  Unity Editor   │
                                           │    (Plugin)     │
                                           └─────────────────┘

运输方式

  • 工作室：MCP协议的标准输入/输出传输。当服务器由MCP客户端生成时使用。
  • 超文本传输协议：支持WebSocket的HTTP服务器。适用于开发和独立运行服务器。

关键组件

  • 插件中心 (/hub/plugin)：Unity插件连接的WebSocket端点
  • 工具注册表：注册并执行MCP工具（manage_scene、manage_gameobject等）
  • 资源注册表：提供MCP资源（editor_state、project_info等）
  • 端口发现：扫描端口6400-6500以查找Unity实例（传统TCP模式）

HTTP端点

使用HTTP传输运行时(--transport http):

端点 描述
/mcp MCP协议（流式HTTP）-适用于MCP客户端
/health 健康检查-返回JSON状态
/hub/plugin 用于Unity插件连接的WebSocket
/plugin/sessions 列出活动插件会话
/tools/:name 直接工具执行（传统）
/resources/*uri 直接资源读取（遗留）
/register-tools 自定义工具注册

可用工具

服务器为Unity交互公开了这些MCP工具：

工具 说明
manage_scene 场景操作（创建、加载、保存、获取层次结构、截图）
manage_gameobject 游戏对象CRUD和转换
manage_components 添加、删除、修改组件
manage_asset 资产操作（导入、创建、搜索）
manage_material 材质和着色器属性
manage_prefabs 预制阶段作业
manage_script C#脚本管理
manage_editor 编辑器状态（播放/暂停/停止）
run_tests 执行Unity测试
read_console 读取Unity控制台日志
还有更多。..

可用资源

资源URI 描述
mcpforunity://editor_state 当前编辑器状态和设置
mcpforunity://project_info 项目元数据和路径
mcpforunity://instances 连接Unity实例
mcpforunity://custom-tools 项目注册的自定义工具

日志

日志将写入：

  • 标准错误：控制台输出
  • 文件: ~/.unity_mcp/logs/unity_mcp_server.log （每日轮换）

MCP客户端配置

克劳德桌面版

添加到您的Claude桌面配置(~/.config/claude/claude_desktop_config.json 在Linux/Mac上， %APPDATA%\Claude\claude_desktop_config.json 在Windows上）：

{
  "mcpServers": {
    "unity": {
      "command": "path/to/unity-mcp",
      "args": []
    }
  }
}

使用HTTP传输

如果使用HTTP传输单独运行服务器：

{
  "mcpServers": {
    "unity": {
      "url": "http://localhost:8080"
    }
  }
}

发展

项目结构

src/
├── main.rs           # Entry point and CLI
├── lib.rs            # Library root
├── config.rs         # Configuration management
├── error.rs          # Error types
├── server.rs         # HTTP server and routing
├── middleware/       # Request context
├── models/           # Data models and types
├── services/
│   ├── tools/        # MCP tool implementations
│   └── resources/    # MCP resource implementations
├── transport/
│   ├── plugin_hub.rs     # WebSocket hub for Unity
│   ├── plugin_registry.rs # Plugin session tracking
│   ├── unity_transport.rs # Transport abstraction
│   └── legacy/           # TCP framing protocol
├── telemetry/        # Usage telemetry (optional)
└── utils/            # Utility functions

运行测试

cargo test

代码格式化

cargo fmt

代码检查

cargo clippy

与Python实现的差异

这个Rust实现是Unity服务器上原始Python MCP的移植。主要区别：

  • 演出：内存使用率显著降低，启动速度更快
  • 单一二进制：不需要Python解释器或依赖项
  • 类型安全：协议处理的编译时间保证
  • 相同协议：与Unity C#插件完全兼容

Unity插件不需要修改即可与此Rust服务器一起使用。

许可证

麻省理工学院

相关 MCP