Godot MCP Unified Server

关键词

Godot资源管理工具执行JSON-RPC 服务编辑器桥接

使用说明（简要，便于上手）

  • 项目简介

    • 该仓库实现了一个可运行的 MCP 服务器，用于向大语言模型客户端提供 Godot 相关的上下文信息、工具调用能力以及提示模板渲染等服务。服务器通过 JSON-RPC 与客户端通信，内部集成 Godot 引擎操作、资源/脚本/场景管理等工具集合，并具备 Editor 插件桥接能力以获得更实时的交互能力。

  • 主要功能点

    • MCP 核心能力：以标准化方式暴露 Resources (资源), Tools (工具), Prompts (提示模板) 的读写与执行能力。
    • JSON-RPC 通信：服务器端接收客户端请求并返回标准的 JSON-RPC 响应或通知。
    • 资源管理：对 Godot 工程中的资源进行 CRUD、导入、重导入等操作。
    • 工具注册与执行：82+ 工具覆盖场景、脚本、UI、动画、导航等 Godot 功能，能够通过桥接或本地执行执行工具逻辑。
    • Prompts 与模板：定义与渲染用于 LLM 交互的 Prompt 模板，支持可定制的对话模式。
    • 桥接能力：通过 Ollama/Bridge 实现 Godot 编辑器插件实时集成，或者在无插件时退回 CLI/文件 I/O 路径。
    • 多传输与会话管理：设计实现支持 Stdio、SSE、WebSocket 等传输模式，适配不同部署场景。

  • 安装与运行步骤

    1. 安装前提
      • Node.js 环境
    2. 安装与构建
      • 在项目目录执行：npm install
      • 构建服务器：npm run build
    3. 启动服务器
      • 启动命令通常为 Node 运行打包后的入口，例如 node build/index.js（具体路径按实际构建输出为准）
      • 启动后默认监听 WebSocket/JSON-RPC 端口，常用端口为 ws://localhost:6505，供 MCP 客户端（如 Claude Desktop/ Claude Code 等）连接。
    4. 与 Godot 的桥接
      • 当 Godot 插件开启且 bridge 可用时，将优先使用桥接实现，提升实时性。
      • 如无桥接，工具将回退到本地 Godot 运行/文件 I/O 的方式执行。

  • 服务器配置（MCP 客户端使用的配置信息，JSON 格式，需你在客户端配置中填写） 说明：客户端需要知道 MCP 服务器的启动命令与参数，便于建立连接。以下为基于仓库信息的准确示例配置要点，实际使用时请按你的部署路径调整参数。

    { "serverName": "godot-mcp-unified", "command": "node", "args": ["build/index.js"], "workingDirectory": "C:\Dev\godot-mcp-unified", "env": { "GODOT_PATH": "C:\Dev\Godot_v4.x-stable_win64_console.exe" // Godot 可执行文件路径（根据你的系统调整） }, "description": "Godot MCP Unified 服务端，向客户端提供资源、工具与提示等 MCP 能力的 JSON-RPC 服务" }

    说明

    • serverName: 客户端在连接并管理服务器时使用的标识名称。
    • command: 启动服务器的命令，可以是 node、npm 运行脚本等。
    • args: 启动命令的参数，示例中指向构建输出的入口文件。
    • workingDirectory: 服务器运行时的工作目录，用于解析相对路径与依赖。
    • env: 运行时环境变量（如 GODOT_PATH 指向 Godot 控制台可执行程序的路径）。
    • description: 给客户端的简要说明，便于管理和日志记录。 注意：以上配置是为 MCP 客户端与服务器对接提供的参考示例，实际使用时请根据你的部署环境调整路径和参数。

  • 基本使用方法

    • 启动后，确保 Godot 引擎及编辑器插件（如果需要桥接）已正确配置并运行。
    • 客户端通过 JSON-RPC 请求向 MCP 服务器获取：
      • 资源读取与管理接口
      • 工具执行请求
      • 提示模板获取与渲染
    • 在 Godot 与 MCP 插件桥接开启时，编辑器内的相关操作会通过桥接实时同步，未开启桥接时将退回 CLI/文件 I/O 的执行路径。

  • 关键注意事项

    • MCP 服务器需要访问 Godot 的可执行路径，通常通过 GODOT_PATH 环境变量指定。
    • 服务器实现包含完整的工具集注册、资源与场景管理、以及不同领域（场景、脚本、资源、UI、动画、导航等）的工具执行逻辑，具备较为全面的 MCP 功能覆盖。
    • 集成测试高度丰富，包含多种集成与单元测试用例，确保核心功能在不同场景下的稳定性。

  • 参考信息

    • 服务器入口与桥接实现均基于仓库提供的结构与代码组织，包含 src/index.ts、src/server、src/bridge、src/core、src/tools 等模块，覆盖 MCP 服务端的核心职责。

服务器信息

访问项目