如何用 Docker 启动 MCP for Unity 服务器并接入 MCP 客户端【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcpMCP for Unity 由两部分组成Unity Editor 内的插件Bridge和独立的 Python MCP 服务器。这篇文章解决的任务是用 Docker 启动其中的 Python 服务器并把 Cursor、VS Code 等 MCP 客户端接上去最终能在客户端里用自然语言驱动 Unity Editor。适用前提是你已经在 Unity 项目中安装了 Unity MCP Plugin这是 Server/DOCKER_OVERVIEW.md 明确标注的 Required 项插件安装路径见 website/docs/getting-started/install.md要求 Unity 2021.3 LTS 或更新版本并且机器上有可用的 Docker 环境。按照 website/docs/architecture/transports.md 中的选型表Remote-hosted server (cloud, Docker) 对应的传输方式是 HTTP。stdio 传输由 MCP 客户端本地拉起 Python 进程文档明确说明其 Cannot host remotely因此 Docker 部署走 HTTP。拉取并启动官方镜像主路径按 Server/DOCKER_OVERVIEW.md 的 Quick Start两步启动docker pull msanatan/mcp-for-unity-server:latestdocker run -p 8080:8080 msanatan/mcp-for-unity-server:latest文档说明该命令启动后 This starts the MCP server on port 8080。需要留意文档间的一处差异仓库内 Server/Dockerfile 的注释写明镜像默认使用 stdio 传输Docker MCP Gateway 兼容而 HTTP 模式需要显式传参根目录的 docker-compose.yml 正是这样做的其启动命令为uv run python src/main.py --transport http --http-host 0.0.0.0 --http-port 8080如果你拉取镜像后发现 8080 端口上没有 HTTP 服务在docker run后面补上相同的参数即可docker run -p 8080:8080 msanatan/mcp-for-unity-server:latest \ --transport http --http-host 0.0.0.0 --http-port 8080可选的环境变量来自 Server/DOCKER_OVERVIEW.mdDISABLE_TELEMETRYtrue— 关闭匿名使用统计LOG_LEVELDEBUG— 开启详细日志默认 INFOdocker run -p 8080:8080 -e LOG_LEVELDEBUG msanatan/mcp-for-unity-server:latest可选分支从仓库源码用 Compose 构建如果你要基于本仓库代码而不是发布镜像来跑服务器可以在仓库根目录直接使用 docker-compose.yml。该文件从仓库根目录构建dockerfile: Server/Dockerfile映射8080:8080设置restart: unless-stopped和PYTHONPATH/app/Server/src并固定以 HTTP 模式、0.0.0.0:8080启动docker compose up --build构建过程会在镜像内执行uv sync --frozen --no-dev安装依赖见 Server/Dockerfile基础镜像为python:3.13-slim。配置 MCP 客户端服务器与 Unity Editor 之间无需额外配置——文档说明 The server connects to the Unity Editor automatically when both are running。你要做的只是让 MCP 客户端指向服务器的 HTTP 端点。在客户端的 MCP 配置中加入Server/DOCKER_OVERVIEW.md 给出的配置{ mcpServers: { UnityMCP: { url: http://localhost:8080/mcp } } }如果客户端不在运行 Docker 的同一台机器上把localhost换成服务器主机地址。VS Code 的配置结构不同website/docs/getting-started/install.md 给出的写法是{ servers: { unityMCP: { type: http, url: http://localhost:8080/mcp } } }一个边界要提前知道Claude Desktop 只支持 stdio 传输website/docs/getting-started/install.md 与 website/docs/architecture/transports.md 均说明而 stdio 无法远程托管所以这篇 Docker HTTP 的部署方式不适用于 Claude Desktop。验证连接按文档给出的检查顺序确认整条链路服务器在 8080 监听——docker run执行后按文档说明服务器运行在 8080 端口。若客户端连不上website/docs/getting-started/install.md 的排查项是确认 HTTP 服务器确实在localhost:8080运行且客户端配置里的 URL 与之完全一致。Unity 侧状态——在 Unity Editor 打开Window → MCP for Unity查看状态面板文档说明当链路全部打通时状态面板显示Connected。出现 Unity Bridge not connecting 时的处理是重启 Unity Editor。发一条真实 prompt——Server/DOCKER_OVERVIEW.md 给出的连接成功后的示例 prompt 包括List all GameObjects in the current scene客户端能返回当前场景的 GameObject 列表说明 MCP 客户端 → Docker 服务器 → Unity Editor 整条路径已通。可选分支远程托管模式API Key 鉴权如果你要把这个 Docker 容器作为多人共享的远程服务部署需要开启 remote-hosted 模式。该模式下所有 MCP 工具/资源调用和 Unity 插件的 WebSocket 连接都必须携带有效的X-API-Key并且每个用户只能看到用自己 API key 连接的 Unity 实例。启动命令Server/DOCKER_OVERVIEW.mddocker run -p 8080:8080 \ -e UNITY_MCP_HTTP_REMOTE_HOSTEDtrue \ -e UNITY_MCP_API_KEY_VALIDATION_URLhttps://auth.example.com/api/validate-key \ -e UNITY_MCP_API_KEY_LOGIN_URLhttps://app.example.com/api-keys \ msanatan/mcp-for-unity-server:latestUNITY_MCP_API_KEY_VALIDATION_URL是必填项它指向一个外部鉴权端点服务器把 API key 校验完全委托给该端点自己不管理 key。website/docs/guides/remote-server-auth.md 说明设置了--http-remote-hosted但缺少 validation URL 时服务器记录错误并以退出码 1 终止。示例中的auth.example.com/app.example.com是文档示例值必须替换为你自己的鉴权服务地址该端点的请求/响应契约{api_key: key}入参valid/user_id出参5 秒超时、失败即拒绝见同一指南的 Validation Contract 一节。其余远程托管相关环境变量Server/DOCKER_OVERVIEW.md变量说明UNITY_MCP_HTTP_REMOTE_HOSTED开启远程托管模式true、1或yesUNITY_MCP_API_KEY_LOGIN_URL用户获取/管理 API key 的页面地址UNITY_MCP_API_KEY_CACHE_TTL已验证 key 的缓存秒数默认300UNITY_MCP_API_KEY_SERVICE_TOKEN_HEADER服务器向鉴权服务自证身份所用的请求头名UNITY_MCP_API_KEY_SERVICE_TOKEN发送给鉴权服务的 token 值客户端配置要加上X-API-Key头your-api-key替换为实际 key{ mcpServers: { UnityMCP: { url: http://your-server:8080/mcp, headers: { X-API-Key: your-api-key } } } }Unity 侧的设置是在MCP for Unity窗口选择 HTTP Remote 连接模式在 API Key 字段填入 key存于 EditorPrefs按机器生效需要新 key 时点Get API Key从服务器/api/auth/login-url端点取登录页地址。远程托管模式的行为变化website/docs/guides/remote-server-auth.md需要写入运维预期本地模式下服务器会自动选中唯一连接的 Unity 实例远程托管模式下自动选择被禁用用户必须显式调用set_active_instance参数为mcpforunity://instances资源中的Namehash。POST /api/command、GET /api/instances、GET /api/custom-tools这三个 REST 端点在该模式下被禁用防止未认证访问。/healthGET用于负载均衡与健康监控和/api/auth/login-urlGET始终可访问可用于容器健康检查。Server/Dockerfile 注释另建议远程托管部署时应加上--project-scoped-tools参数。常见问题以下条目均出自 website/docs/guides/remote-server-auth.md 的 Troubleshooting 与 website/docs/getting-started/install.md 的 Troubleshooting服务器启动后立即以退出码 1 终止--http-remote-hosted需要配套的 validation URL。通过 CLI 参数或UNITY_MCP_API_KEY_VALIDATION_URL环境变量提供。每次工具调用都报 API key authentication required服务器处于远程托管模式但请求没带 API key。检查客户端配置是否包含X-API-Key头或 Unity 插件连接设置里是否填了 key。WebSocket 连接被 4401 关闭Unity 插件没有发送 API key在 MCP for Unity 窗口的连接设置中填入。WebSocket 连接被 1013 关闭外部鉴权服务不可达。检查 MCP 服务器到 validation URL 的网络连通性Unity 插件可以重试。用户看不到自己的 Unity 实例会话隔离生效中Unity 插件与 MCP 客户端必须使用解析到同一个user_id的 API key。密钥轮换后旧 key 仍短暂可用已验证 key 按--api-key-cache-ttl默认 300 秒缓存旧 key 失效有等于 TTL 的延迟调低 TTL 可加快吊销代价是更频繁的校验请求。相关文档Docker 快速启动与环境变量Server/DOCKER_OVERVIEW.md容器编排与源码构建配置docker-compose.yml、Server/DockerfileUnity 插件安装与客户端手动配置website/docs/getting-started/install.md远程服务器 API Key 鉴权完整指南website/docs/guides/remote-server-auth.mdHTTP / stdio 传输模式选型website/docs/architecture/transports.md【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考