UnityMCP

Unity MCP 集成框架

🌟 特性

• 可扩展的插件架构: 创建和注册自定义处理器以扩展功能

• 完整的 MCP 集成: 支持命令、资源和提示等所有 MCP 基本功能

• TypeScript & C# 支持: 服务器组件使用 TypeScript，Unity 组件使用 C#

• 编辑器集成: 作为具有可定制设置的编辑器工具运行

• 自动检测: 自动检测和注册各种处理器

• 通信: Unity 与外部 AI 服务之间的 TCP/IP 通信

📋 系统要求

• Unity 2022.3.22f1 或更高版本（支持 Unity6）
• 已在 2022.3.22f1, 2023.2.19f1, 6000.0.35f1 上测试

• .NET/C# 9.0

• Node.js 18.0.0 或更高版本及 npm（用于 TypeScript 服务器）
• 从 Node.js 官方网站 安装

🚀 快速开始

安装方法

1. 使用 Unity 包管理器安装:
• 打开包管理器 (Window > Package Manager)
• 点击“+”按钮
• 选择“Add package from git URL...”
• 输入: https://github.com/isuzu-shiranui/UnityMCP.git?path=jp.shiranui-isuzu.unity-mcp

快速设置

1. 打开 Unity，导航到 Edit > Preferences > Unity MCP

2. 配置连接设置（主机和端口）

3. 点击“Connect”按钮开始监听连接

与 Claude Desktop 集成

1. 从发布页面下载最新的 ZIP 文件并解压

2. 记录 build/index.js 文件的完整路径

3. 打开 Claude Desktop 的配置文件 claude_desktop_config.json

4. 添加以下内容并保存:

🔌 架构

1. Unity C# 插件

• McpServer: 监听 TCP 连接并路由命令的核心服务器

• IMcpCommandHandler: 创建自定义命令处理器的接口

• IMcpResourceHandler: 创建数据提供资源的接口

• McpSettings: 管理插件设置

• McpServiceManager: 服务管理的依赖注入系统

• McpHandlerDiscovery: 自动检测和注册各种处理器

2. TypeScript MCP 客户端

• HandlerAdapter: 将各种处理器适配到 MCP SDK

• HandlerDiscovery: 检测和注册处理器实现

• UnityConnection: 管理与 Unity 的 TCP/IP 通信

• BaseCommandHandler: 命令处理器实现的基类

• BaseResourceHandler: 资源处理器实现的基类

• BasePromptHandler: 提示处理器实现的基类

📄 MCP 处理器类型

1. 命令处理器（工具）

• 用途: 执行操作的工具（在 Unity 中执行某些操作）

• 控制: 模型控制型 - AI 模型可自动调用

• 实现: 实现 IMcpCommandHandler 接口

2. 资源处理器（资源）

• 用途: 访问 Unity 内部数据的资源（提供信息）

• 控制: 应用程序控制型 - 客户端应用程序决定使用

• 实现: 实现 IMcpResourceHandler 接口

3. 提示处理器（提示）

• 用途: 可重用的提示模板和工作流

• 控制: 用户控制型 - 用户明确选择使用

• 实现: 实现 IPromptHandler 接口（仅 TypeScript 侧）

🔬 示例代码

1. Unity MCP 处理器示例
• C# 实现的示例代码
• 可直接导入项目中使用

2. Unity MCP 处理器示例 JavaScript
• JavaScript 实现的示例代码
• 将 JS 文件复制到 build/handlers 目录中使用

⚠️ 注意: 示例代码包含任意代码执行功能，生产环境中使用时需谨慎。

1. 在 Unity 包管理器中选择本包

2. 点击“Samples”标签

3. 点击所需示例的“Import”按钮

🛠️ 创建自定义处理器

命令处理器 (C#)

资源处理器 (C#)

命令处理器 (TypeScript)

资源处理器 (TypeScript)

提示处理器 (TypeScript)

🔄 通信流程

1. Claude（或其他 AI）调用 MCP 的某个功能（工具/资源/提示）

2. TypeScript 服务器通过 TCP 将请求转发到 Unity

3. Unity 的 McpServer 接收请求并找到合适的处理器

4. 处理器在 Unity 主线程中处理请求

5. 结果通过 TCP 连接返回到 TypeScript 服务器

6. TypeScript 服务器格式化结果并返回给 Claude

⚙️ 配置

Unity 配置

• Host: 服务器绑定的 IP 地址（默认: 127.0.0.1）

• Port: 监听的端口（默认: 27182）

• UDP Discovery: 启用 TypeScript 服务器的自动检测

• Auto-start on Launch: Unity 启动时自动启动服务器

• Auto-restart on Play Mode Change: 播放模式开始/结束时自动重启服务器

• Detailed Logs: 启用调试用的详细日志

TypeScript 配置

• MCP_HOST: Unity 服务器主机（默认: 127.0.0.1）

• MCP_PORT: Unity 服务器端口（默认: 27182）

🔍 故障排除

常见问题

1. 连接错误
• 检查 Unity 侧的防火墙设置
• 确认端口号配置正确
• 确认没有其他进程占用相同端口

2. 处理器未注册
• 确认处理器类正确实现了接口
• 确认 C# 处理器的访问级别为 public 或 internal
• 检查 Unity 侧日志，确认注册过程中未发生错误

3. 资源未找到
• 确认资源名称和 URI 匹配
• 确认资源处理器已正确启用

日志检查

• Unity 控制台: 查看 McpServer 的日志消息

• TypeScript 服务器: 使用 MCP Inspector 等工具在控制台输出中检查通信错误

📚 内置处理器

Unity (C#)

• MenuItemCommandHandler: 执行 Unity 编辑器菜单项

• ConsoleCommandHandler: 操作 Unity 控制台日志

• AssembliesResourceHandler: 获取程序集信息

• PackagesResourceHandler: 获取包信息

TypeScript

• MenuItemCommandHandler: 执行菜单项

• ConsoleCommandHandler: 操作控制台日志

• AssemblyResourceHandler: 获取程序集信息

• PackageResourceHandler: 获取包信息

📖 外部资源

• Model Context Protocol (MCP) 规范

⚠️ 安全注意事项

1. 不要执行不受信任的处理器: 使用第三方创建的处理器代码前，请先进行安全审查。

2. 限制代码执行权限: 特别是包含 code_execute 命令的处理器可以执行任意代码，建议在生产环境中禁用。

📄 许可证