Unity MCP Server Docker 部署全指南从本地 Quick Start 到 API Key 鉴权的远程托管模式【免费下载链接】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-mcpUnity MCPModel Context ProtocolServer 是连接 AI 助手如 Claude、Cursor与 Unity Editor 的桥梁而 Docker 镜像为其提供了最干净、最可复现的部署方式无需在本机安装 Python 与 uv一条docker run即可在任意平台拉起 MCP 服务。本文以仓库中的 Server/DOCKER_OVERVIEW.md 为骨架结合 Server/Dockerfile、Server/src/main.py 等源码完整讲解镜像拉取、服务启动、MCP 客户端对接、环境变量配置并深入剖析用于团队共享部署的Remote-Hosted 远程托管模式API Key 鉴权 按用户会话隔离。读完本文你将具备从本地联调到远程多用户部署的完整 Docker 实战能力。前置说明本指南基于仓库内当前版本的 Server包版本见 Server/pyproject.toml名称为mcpforunityserver。使用 Docker 部署前仍需在 Unity Editor 中安装并配置 Unity MCP 插件插件负责与 MCP Server 建立 WebSocket 连接二者缺一不可。Quick Start三分钟跑起一个 MCP Server1. 拉取镜像docker pull msanatan/mcp-for-unity-server:latest2. 运行服务docker run -p 8080:8080 msanatan/mcp-for-unity-server:latest命令将容器的 8080 端口映射到宿主机 8080MCP Server 随即启动。若你希望显式以 HTTP 传输方式暴露服务官方推荐做法可以在镜像名后追加运行时参数docker run -p 8080:8080 msanatan/mcp-for-unity-server:latest --transport http --http-url http://0.0.0.0:80803. 配置 MCP 客户端在任意 MCP 客户端如 Claude Desktop 配置、Cursor 设置中加入如下配置{ mcpServers: { UnityMCP: { url: http://localhost:8080/mcp } } }配置完成后AI 助手即可通过该 URL 调用 Unity 相关工具与资源。注意MCP 端点路径固定为/mcp这是 MCP over HTTP 的约定端点客户端配置时必须完整填写。Docker 镜像内部构造读懂 Dockerfile 再部署直接使用镜像固然简单但了解镜像的构建方式能帮助你判断何时需要覆盖启动参数、如何定制构建。仓库根目录的 Server/Dockerfile 是唯一的构建入口其关键设计如下配置项取值说明基础镜像python:3.13-slim精简版 Python 3.13 运行时依赖管理uv sync --frozen --no-dev依据 Server/uv.lock 冻结依赖不安装 dev 依赖缩小镜像体积Python 运行环境PYTHONUNBUFFERED1、PIP_NO_CACHE_DIR1关闭输出缓冲、禁用 pip 缓存以减小层体积uv 行为UV_LINK_MODEcopy、UV_PYTHON_DOWNLOADS0包以 copy 模式装入 venv只读层更安全不自动下载 Python 运行时系统依赖ca-certificates、git证书与 git供按 Git 源码安装包等场景使用工作目录/app/Server与源码仓库的 Server 目录结构一致暴露端口EXPOSE 8080容器内 8080 端口Python 路径PYTHONPATH/app/Server/src使src下的模块可被直接导入入口ENTRYPOINT [uv, run, mcp-for-unity]默认执行mcp-for-unity命令见 Server/pyproject.toml 的[project.scripts]定义可通过docker run后的参数覆盖需要特别留意的点是ENTRYPOINT 默认走 stdio 传输Dockerfile 注释明确说明其默认设计兼容 Docker MCP Gateway而容器内没有 TTY 交互时 stdio 模式通常用于被 MCP 客户端以子进程方式拉起。因此当你想通过宿主机端口访问服务时应显式追加--transport http --http-host 0.0.0.0 --http-port 8080参数让服务以 HTTP 方式对外提供/mcp端点。本地构建镜像若不想使用预构建镜像如需要修改 Server 源码可在仓库根目录执行docker build -t unity-mcp-server . docker run -p 8080:8080 unity-mcp-server --transport http --http-url http://0.0.0.0:8080构建上下文为仓库根目录Dockerfile 路径为Server/DockerfileCOPY . /app将整个仓库复制进镜像后再切换到/app/Server执行依赖同步。使用 docker-compose 一键编排仓库根目录提供了开箱即用的 docker-compose.yml适合需要固定配置、自动重启的部署场景version: 3.9 services: unity-mcp-server: build: context: . dockerfile: Server/Dockerfile ports: - 8080:8080 restart: unless-stopped environment: - PYTHONPATH/app/Server/src command: [uv, run, python, src/main.py, --transport, http, --http-host, 0.0.0.0, --http-port, 8080]使用docker compose up -d即可后台启动。可以看到 compose 文件中以command显式指定了 HTTP 传输方式与监听地址并把环境变量如远程托管模式、API Key 配置、日志级别追加到environment段即可完成参数注入无需记忆一长串-e参数。服务配置环境变量与 CLI 参数服务器在 Server 与 Unity Editor 同时运行时自动建立连接大多数场景无需额外配置。需要调整时可通过环境变量或命令行参数完成。由于 Docker 下最常用的是环境变量这里以 Server/README.md 和 Server/src/main.py 中的解析逻辑为准整理为下表。基础环境变量环境变量默认值说明DISABLE_TELEMETRY未设置设为true/1/yes可退出匿名使用统计UNITY_MCP_DISABLE_TELEMETRY、MCP_DISABLE_TELEMETRY与之等价LOG_LEVELINFO日志级别设为DEBUG可开启详细日志UNITY_MCP_TRANSPORTstdio传输协议stdio或httpUNITY_MCP_HTTP_URLhttp://localhost:8080HTTP 服务基础 URL用于推导 host/port 默认值UNITY_MCP_HTTP_HOST由 URL 推导HTTP 绑定地址覆盖 URL 中的 host远程部署常用0.0.0.0UNITY_MCP_HTTP_PORT由 URL 推导默认 8080HTTP 绑定端口覆盖 URL 中的 portUNITY_MCP_SKIP_STARTUP_CONNECT未设置设为1时跳过启动时的 Unity 首次连接尝试对应 Server/src/main.py 中的启动逻辑UNITY_MCP_LOG_DIR各平台约定目录覆盖轮转日志目录Windows 为%LOCALAPPDATA%\UnityMCP\LogsmacOS 为~/Library/Application Support/UnityMCP/LogsLinux/BSD 为$XDG_STATE_HOME/UnityMCP/Logs缺省回退~/.local/state/UnityMCP/Logs带环境变量的运行示例docker run -p 8080:8080 -e LOG_LEVELDEBUG msanatan/mcp-for-unity-server:latest对应的 CLI 参数Docker 下追加在镜像名之后对于同样一份配置命令行参数是环境变量的替代方案二者优先级为「命令行 环境变量 默认值」CLI 参数说明--transport {stdio,http}传输协议默认stdio--http-url URLHTTP 基础 URL默认http://127.0.0.1:8080--http-host HOST覆盖 HTTP 绑定地址--http-port PORT覆盖 HTTP 绑定端口--default-instance INSTANCE默认目标 Unity 实例项目名、hash 或Namehash--project-scoped-tools将自定义工具限定在当前 Unity 项目并启用自定义工具资源--unity-instance-token TOKENUnity 每次启动时写入的令牌用于确定性的生命周期管理--pidfile PATH启动时写入 PID 的路径供 Unity 托管终端启动时精确停止进程源码提示以上参数的解析、校验与默认值处理全部集中在 Server/src/main.py 的main()中HTTP host/port 的推导顺序为「CLI 参数 → 环境变量 → URL 组件 → 内置默认」其中UNITY_MCP_HTTP_PORT若为非法数值会被安全忽略并回退到默认端口。Remote-Hosted 模式共享远程服务的 API Key 鉴权部署当需要把 MCP Server 部署为团队共享的远程服务例如为多个开发者或 Asset Store 用户提供服务时应启用Remote-Hosted 模式。该模式下服务强制启用 API Key 鉴权并实现按用户的会话隔离。启用方式Docker 部署时在环境变量中同时注入远程托管开关与鉴权服务地址docker 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:latest等价地也可以在镜像名后追加--http-remote-hosted --api-key-validation-url ... --api-key-login-url ...命令行参数两个入口最终都会写入 Server/src/core/config.py 的全局config对象。远程托管环境变量完整变量说明UNITY_MCP_HTTP_REMOTE_HOSTED启用远程托管模式取值true、1或yesUNITY_MCP_API_KEY_VALIDATION_URL外部 API Key 校验端点必填UNITY_MCP_API_KEY_LOGIN_URL用户获取/管理 API Key 的页面地址UNITY_MCP_API_KEY_CACHE_TTL已校验 Key 的缓存时长秒默认300UNITY_MCP_API_KEY_SERVICE_TOKEN_HEADER服务端到鉴权服务的认证 Header 名如X-Service-TokenUNITY_MCP_API_KEY_SERVICE_TOKEN发送给鉴权服务的令牌值远程托管模式的行为变化启用后服务行为发生如下变化与 Server/README.md 及 Server/src/main.py 中的实现一致全面鉴权所有 MCP 工具/资源调用以及 Unity 插件的 WebSocket 连接都必须携带有效的X-API-KeyHeader。会话隔离每个用户只能看到使用自己 API Key 连接的 Unity 实例。显式实例选择自动选中唯一实例的行为被禁用用户必须显式调用set_active_instance才能选定目标 Unity 实例。禁用本地 CLI 路由仅面向本地的/api/command、/api/instances、/api/custom-toolsREST 路由被关闭见 Server/src/main.py 中if not config.http_remote_hosted的条件注册。保留公开端点/health与/api/auth/login-url仍无需鉴权即可访问——前者用于健康检查后者用于向前端返回“获取 API Key”的登录页面地址。MCP 客户端配置带 API Key{ mcpServers: { UnityMCP: { url: http://your-server:8080/mcp, headers: { X-API-Key: your-api-key } } } }Unity 插件的 MCP 客户端配置器在 API Key 已配置时会自动在生成的配置文件中附加X-API-KeyHeader对于 CLI 型客户端如 Claude Code则通过claude mcp add --transport http ... --header X-API-Key: key注入。启动校验与验证契约远程托管模式对配置有强制校验若设置了--http-remote-hosted或对应环境变量但未提供--api-key-validation-url服务会在启动时记录错误并以退出码 1 终止见 Server/src/main.py因此部署前务必确认校验端点可达。外部鉴权服务的交互契约详见仓库文档 website/docs/guides/remote-server-auth.md服务向UNITY_MCP_API_KEY_VALIDATION_URL发送POST请求JSON 体为{api_key: key}期望响应为{valid: true, user_id: ...}附带可选metadata或{valid: false}若配置了服务令牌每次校验请求会附带UNITY_MCP_API_KEY_SERVICE_TOKEN_HEADER: token用于服务端到鉴权服务之间的双向认证。底层实现缓存、失败策略与会话隔离Server/src/services/api_key_service.py 是远程托管模式的核心实现其设计值得注意TTL 缓存验证结果以api_key - (valid, user_id, metadata, expires_at)的形式缓存在内存中默认 300 秒可用UNITY_MCP_API_KEY_CACHE_TTL调整有效期内重复请求不会反复打到鉴权服务。Fail-Closed 失败策略鉴权服务超时、不可达或返回非 200 状态时一律按“无效 Key”拒绝访问fail closed同时这类瞬时失败不会写入缓存cacheableFalse避免鉴权服务故障期间将用户“锁定”在无效状态。Key 脱敏日志中的 API Key 仅保留前 4 位与后 4 位避免密钥泄漏到日志。会话隔离用户身份由鉴权服务返回的user_id决定Unity 实例的注册与路由都与其 API Key 绑定详见 Server/src/transport/unity_instance_middleware.py 与 Server/src/transport/plugin_registry.py。Unity 插件侧的连接设置使用远程托管服务时Unity 用户在插件窗口中按以下步骤接入打开 Unity Editor 中的 MCP for Unity 窗口连接模式选择HTTP Remote在 API Key 字段输入自己的 KeyKey 保存在EditorPrefs中仅本机有效、不入库如需新 Key点击Get API Key在浏览器中打开登录页——该地址由服务器/api/auth/login-url端点下发。健康检查与运维提示HTTP 传输模式下服务在/health端点暴露健康状态注册于 Server/src/main.py返回示例{ status: healthy, timestamp: 1737000000.0, version: 10.2.0, message: MCP for Unity server is running }你可以用它配置 Docker 的HEALTHCHECK或编排平台的探针配合docker-compose.yml中的restart: unless-stopped可在异常退出后自动恢复。调试阶段建议将LOG_LEVEL设为DEBUG观察详细日志服务还会按操作系统约定目录写入轮转日志文件单文件 512KB、保留 2 份备份见 Server/src/main.pystdio 启动模式下排查问题同样有日志可查。连接成功后的示例提示词服务接入后可以直接在 AI 助手中尝试以下指令与 Server/DOCKER_OVERVIEW.md 保持一致Create a 3D player controller with WASD movementAdd a rotating cube to the scene with a red materialCreate a simple platformer level with obstaclesGenerate a shader that creates a holographic effectList all GameObjects in the current scene常见问题排查思路端口无法访问确认启动命令中包含--transport http --http-host 0.0.0.0 --http-port 8080或设置UNITY_MCP_TRANSPORThttp因为镜像默认 ENTRYPOINT 走 stdio。MCP 端点 404客户端 URL 必须指向/mcp端点且 HTTP transport 已启用。远程托管启动即退出检查是否漏配UNITY_MCP_API_KEY_VALIDATION_URL——缺少时服务会以退出码 1 拒绝启动。鉴权被拒但 Key 正确确认鉴权服务返回{valid: true, user_id: ...}结构并留意缓存 TTL默认 300 秒内 Key 状态变更可能不会立即生效。多实例路由错误远程托管模式下不会自动选择唯一实例需在会话中显式调用set_active_instance实例标识格式为Namehash。延伸阅读Server/DOCKER_OVERVIEW.mdDocker 部署官方速览Server/README.md完整的 CLI 参数、环境变量与 MCP Resources 说明Server/Dockerfile 与 docker-compose.yml镜像与编排的构建依据Server/src/main.py启动流程、参数解析与远程托管校验Server/src/services/api_key_service.pyAPI Key 校验、缓存与失败策略website/docs/guides/remote-server-auth.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），仅供参考