☰

企业官网建设流程全解析

首页 / 建站日记 / 企业官网建设流程全解析
如何用 Docker 启动 MCP for Unity 服务器并接入 MCP 客户端
2026/9/15 15:34:37 网站建设 项目流程

如何用 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-mcp

MCP 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:latest
docker 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.md）：

  • DISABLE_TELEMETRY=true— 关闭匿名使用统计
  • LOG_LEVEL=DEBUG— 开启详细日志（默认 INFO）
docker run -p 8080:8080 -e LOG_LEVEL=DEBUG 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。

验证连接

按文档给出的检查顺序确认整条链路：

  1. 服务器在 8080 监听——docker run执行后按文档说明服务器运行在 8080 端口。若客户端连不上，website/docs/getting-started/install.md 的排查项是：确认 HTTP 服务器确实在localhost:8080运行，且客户端配置里的 URL 与之完全一致。

  2. Unity 侧状态——在 Unity Editor 打开Window → MCP for Unity，查看状态面板；文档说明当链路全部打通时状态面板显示Connected。出现 "Unity Bridge not connecting" 时的处理是重启 Unity Editor。

  3. 发一条真实 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.md）：

docker run -p 8080:8080 \ -e UNITY_MCP_HTTP_REMOTE_HOSTED=true \ -e UNITY_MCP_API_KEY_VALIDATION_URL=https://auth.example.com/api/validate-key \ -e UNITY_MCP_API_KEY_LOGIN_URL=https://app.example.com/api-keys \ msanatan/mcp-for-unity-server:latest

UNITY_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或yes）
UNITY_MCP_API_KEY_LOGIN_URL用户获取/管理 API key 的页面地址
UNITY_MCP_API_KEY_CACHE_TTL已验证 key 的缓存秒数（默认300）
UNITY_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资源中的Name@hash）。
  • POST /api/command、GET /api/instances、GET /api/custom-tools这三个 REST 端点在该模式下被禁用，防止未认证访问。
  • /health（GET，用于负载均衡与健康监控）和/api/auth/login-url（GET）始终可访问，可用于容器健康检查。
  • 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/Dockerfile
  • Unity 插件安装与客户端手动配置：website/docs/getting-started/install.md
  • 远程服务器 API Key 鉴权完整指南：website/docs/guides/remote-server-auth.md
  • HTTP / 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），仅供参考

标签： 网站建设 企业官网 项目流程 UI设计 前端开发

热门文章

文章分类

标签云

网站建设 响应式设计 用户体验 SEO优化 前端开发 小程序 电商平台 性能优化

相关文章

您可能感兴趣的其他内容

FiftyOne 数据集动物园之 RoboLab-EgoX：机器人操作策略回放的 .mcap 多模态数据集实战指南
2026/9/15 15:34:00 网站建设

FiftyOne 数据集动物园之 RoboLab-EgoX：机器人操作策略回放的 .mcap 多模态数据集实战指南

FiftyOne 数据集动物园之 RoboLab-EgoX&#xff1a;机器人操作策略回放的 .mcap 多模态数据集实战指南 【免费下载链接】fiftyone Refine high-quality datasets and visual AI models 项目地址: https://gitcode.com/GitHub_Trending/fi/fiftyone 导读 本文围绕 Fifty…...

阅读更多 →
Instructor 字段级流式输出实战：用 create_partial 把 LLM 结构化结果实时渲染到前端
2026/9/15 15:33:18 网站建设

Instructor 字段级流式输出实战：用 create_partial 把 LLM 结构化结果实时渲染到前端

Instructor 字段级流式输出实战&#xff1a;用 create_partial 把 LLM 结构化结果实时渲染到前端 【免费下载链接】instructor structured outputs for llms 项目地址: https://gitcode.com/GitHub_Trending/in/instructor 本篇技术指南围绕 instructor 的 create_part…...

阅读更多 →
TanStack Solid Start 执行模型全解：同构优先、执行边界控制与安全实践
2026/9/15 15:33:01 网站建设

TanStack Solid Start 执行模型全解：同构优先、执行边界控制与安全实践

TanStack Solid Start 执行模型全解&#xff1a;同构优先、执行边界控制与安全实践 【免费下载链接】router &#x1f916; A client-first, server-capable, fully type-safe router and full-stack framework for the web (React and more). 项目地址: https://gitcode.com…...

阅读更多 →

需要专业的网站建设服务？

联系我们获取免费的网站建设咨询和方案报价，让我们帮助您实现业务目标

立即咨询