AI导哈

Godot游戏开发MCP服务器

godot-mcp是一个无依赖的MCP服务器，用于Godot 4.5+，允许AI代理通过MCP工具调用创建、编辑和运行完整的Godot游戏。

  • by MhrnMhrn
  • Python
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 MhrnMhrn/godot-mcp

使用说明

Godot MCP

godot-mcp 是适用于Godot 4.5+的无依赖性MCP服务器。它允许AI代理完全通过MCP工具调用创建、编辑和运行完整的Godot游戏。

经过测试 法典 和 克劳德。还应与 LMStudio, 开源代码，以及任何其他MCP兼容客户端。

特性

  • 检测Godot (godot_detect_executable)：定位并验证Godot可执行文件，以便每个后续工具都知道要使用哪个引擎二进制文件。

  • 创建项目 (godot_create_project)：使用所选名称和父目录构建一个全新的Godot项目，委托给Godot本身，以便输出与较新的4.x版本保持兼容。

  • 创建文件夹 (godot_create_folder)：使用安全设置创建项目相关文件夹 snake_case 用于组织资源、场景和脚本的命名。

  • 检查项目结构 (godot_get_project_structure)：返回嵌套的结构化条目和项目中所有文件和文件夹的人类可读树字符串。

  • 列出资源 (godot_list_resources)：提供脚本、着色器、场景和纹理的快速分组概述，包括计数，而无需手动对项目进行全局调整。

  • 启动编辑器 (godot_start_project)：打开项目的Godot编辑器，返回PID和日志文件路径。

  • 创建场景 (godot_create_scene)：创建并保存具有Godot样式的新场景 snake_case.tscn 文件名和 PascalCase 根节点名称。

  • 创建着色器 (godot_create_shader)：生成 .gdshader 从启动器模板或显式着色器源代码中获取文件。

  • 更新项目设置 (godot_update_project_settings)：编辑一个或多个 ProjectSettings 通过Godot本身设置参数（应用程序名称、窗口大小等）。通过以下方式接受JSON兼容值和可选的原始Godot表达式 value_godot.

  • 附加脚本 (godot_attach_script)：附加现有 .gd 文件或创建一个启动器脚本，在附加目标节点之前扩展其类型。

  • 获取场景树 (godot_get_scene_tree)：使用Godot自己的检查已保存场景的节点树和父/子结构 PackedScene.get_state().

  • 验证场景 (godot_validate_scene)：Dry run使用轻量级的无头加载解析场景资源，因此问题在完整运行之前就会出现。

  • 添加节点 (godot_add_node)：将任何可实例化的Godot节点类型的新节点添加到现有场景中。

  • 添加基本网格 (godot_add_primitive_mesh)：落在一个 BoxMesh, CylinderMesh, SphereMesh，或上的其他内置图元 MeshInstance3D 用于快速水平封锁的节点。

  • 编辑图元网格 (godot_edit_primitive_mesh)：交换基本体类型或更改大小、高度、半径和分段计数等参数。

  • 编辑场景 (godot_edit_scene)：重命名节点、重新解析节点、删除节点，或在一次保存中将这些编辑与变换更改组合在一起。使用Godot重新打包场景。

  • 获取节点属性 (godot_get_node_properties)：返回具有序列化当前值的属性列表，以便对象和向量值保持JSON友好。

  • 获取节点转换 (godot_get_node_transform)：检查根节点或子节点的变换部分 Node2D, Node3D，以及 Control 节点。

  • 更新节点转换 (godot_update_node_transform)：使用JSON友好的矢量对象调整位置、旋转、缩放或其他支持的变换字段，如 { "x": 10, "y": 20 }.

  • 运行项目 (godot_run_project)：将项目的主场景作为分离进程启动，返回PID和日志文件路径。

  • 运行场景 (godot_run_scene)：直接将特定场景作为分离进程启动。

  • 用Capture跑步 (godot_run_with_capture)：运行一个简短的捕获窗口，然后返回stdout、stderr、Godot日志文件摘录，并解析调试行以查找警告和错误。

  • 截图 (godot_screenshot)：使用Godot的内置电影编写器在短时间运行后捕获最后一个渲染的PNG帧。

  • 搜索文档 (godot_search_docs)：搜索从所选Godot可执行文件生成的缓存API转储，以便结果与安装的引擎版本保持一致。

  • 添加世界环境 (godot_add_world_environment)：添加一个WorldEnvironment节点，并在一次调用中应用环境和节点级参数更新。

  • 更新世界环境 (godot_update_world_environment)：更新现有WorldEnvironment节点的环境设置（雾、色调贴图、环境光、背景等）和选定节点属性。

  • 使用可视化配置文件运行 (godot_run_with_visual_profiler)：分析Godot项目的渲染和视觉性能，报告fps、frame_time_ms、render_objects_in_frame、render_plimitives_in_frames、render_draw_calls_in_fframe、render_video_m_bytes、navigation_process_ms、object_count和node_count等指标。

  • 使用Profiler运行 (godot_run_with_profiler)：使用内置分析器运行Godot项目或特定场景，以捕获详细的性能数据，包括fps、frame_time_ms、process_time_ms，physics_frame_time_m、navigation_process_ms、memory_static_bytes、object_count、resource_count、node_count、孤女节点_count、physics_2d_active_objects、physics-2d_clinsion_pairs、physics_2disland_count、physics_3d_active-objects、physics_3d_clinsion-pairs、physics_idisland_counts和audio_output_latency _ms。

  • 录制视频 （godot_record_video）：在设定的持续时间内运行场景，通过defualt运行.avi，或捕获帧和音频，并通过ffmpeg将结果编码为.mp4（如果可用）。接受camera_waypoints数组（每个关键帧的位置、旋转和FOV）。

服务器还通过stdio公开MCP资源发现，因此客户端可以检查静态工具目录资源和每个工具的详细信息模板，而无需先调用工具。

需求

  • Python 3.10+

  • Godot 4.5或更新版本

  • FFmpeg（可选）

Godot可以提供：

  • 每次工具调用 godot_executable
  • 全球与 GODOT_EXECUTABLE 环境变量

示例：

  • /Applications/Godot.app/Contents/MacOS/Godot
  • /Applications/Godot_mono.app/Contents/MacOS/Godot
  • /usr/local/bin/godot4

运行它

从该存储库：

PYTHONPATH=src python3 -m godot_mcp

或者安装它：

python3 -m pip install -e .
godot-mcp

MCP配置示例

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["-m", "godot_mcp"],
      "env": {
        "PYTHONPATH": "/path/to/godot-mcp/src",
        "GODOT_EXECUTABLE": "/path/to/godot"
      },
      "toolCallTimeoutMillis": 240000
    }
  }
}

调整 "toolCallTimeoutMillis" 根据需要。例如使用视频记录。如果您的录制超过默认超时时间 120000 毫秒（2分钟），相应地增加此值以防止工具调用超时。

备注

  • 场景文件名被标准化为 snake_case.tscn.
  • 项目相关文件夹输入已标准化为安全 snake_case 目录段。
  • 场景根节点名称被规范化为 PascalCase.
  • 着色器文件名被规范化为 snake_case.gdshader.
  • 脚本文件名被规范化为 snake_case.gd 当MCP创建它们时。
  • godot_get_project_structure 返回嵌套的结构化条目和人类可读的树字符串。
  • godot_list_resources 返回分组的项目资源，包括脚本、着色器、场景和纹理的计数。
  • 场景树检查使用Godot自己的 PackedScene.get_state() 而不是手工解析 .tscn 文件夹。
  • godot_validate_scene 使用场景资源的轻量级无头加载，以便在完整运行之前解析问题。
  • godot_add_primitive_mesh 和 godot_edit_primitive_mesh 通过Godot本身工作，因此原始资源保持有效，并且可以通过具有网格特定参数的MCP驱动级别灰箱。
  • MCP资源发现可通过 resources/list, resources/templates/list，以及 resources/read，包括 godot://server/tools, godot://server/guide，以及 godot://tool/{name}.
  • godot_get_node_properties 返回具有序列化当前值的属性列表，以便对象和向量值保持JSON友好。
  • godot_edit_scene 使用Godot在节点编辑后重新打包场景，而不是重写 .tscn 直接文本。
  • 本地文档搜索使用从所选Godot可执行文件生成的缓存API转储，因此结果与安装的引擎版本保持一致。
  • 目前支持转换检查和编辑 Node2D, Node3D，以及 Control 节点，使用JSON友好的向量对象，如 { "x": 10, "y": 20 }.
  • godot_attach_script 可以附加现有 .gd 文件或创建一个启动器脚本，在附加目标节点之前扩展其类型。
  • godot_run_project 和 godot_run_scene 启动已分离的进程，并返回PID和日志文件路径。
  • godot_run_with_capture 运行一个简短的捕获窗口，然后返回stdout、stderr、Godot日志文件摘录，并解析调试行以查找警告和错误。
  • godot_screenshot 使用Godot的内置电影编写器，然后将最后渲染的PNG帧保留为屏幕截图，并清理中间帧。
  • 默认情况下，运行工具是非无头的，因此除非您明确传递，否则会出现一个正常的游戏窗口 headless=true.
  • godot_start_project 打开编辑器并返回PID和日志文件路径。
  • 日志被写入目标项目中 .godot-mcp/logs/.

本地验证

此存储库包括使用虚假Godot可执行文件的单元测试，因此即使当前环境中未安装Godot，也可以验证MCP服务器。

用以下方式运行它们：

python3 -m unittest discover -s tests

贡献

欢迎投稿！您可以随时打开问题、提交pull请求或建议新功能。感谢所有贡献。

许可证

该项目根据 MIT许可证.

相关 MCP