mcpField
G
Godot MCP

Godot MCP

本地服务
github.com开发工具5053 周前更新
代码仓库访问官网

关于 Godot MCP

Godot MCP 是一个 MCP 服务，让 AI 助手通过 157 个工具控制 Godot 4.x 游戏引擎。它面向使用 AI 辅助开发 Godot 项目的开发者，既支持无需运行游戏的场景与项目文件操作，也支持对运行中游戏的检查与修改。项目基于 godot-mcp 扩展而来，并支持 .NET / C# 项目。

主要功能

  1. 01无需运行游戏即可读写 .tscn 与项目设置
  2. 02运行时读写节点属性并调用方法
  3. 03运行时执行 GDScript 并返回结果
  4. 04GDScript 语法与类型校验
  5. 05支持 .NET / C# 项目脚手架

适用场景

  1. 01让 AI 助手在修改脚本后校验 GDScript 错误
  2. 02在运行中的游戏里检查节点、信号与性能数据
  3. 03批量生成或调整场景文件与输入映射

MCP 相关

该项目是 MCP 服务，向 MCP 客户端暴露场景编辑、项目管理、运行时检查与输入模拟等工具，覆盖 Godot 引擎的大量功能。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "tugcantopaloglu-godot": {
      "command": "npx",
      "args": [
        "-y",
        "@tugcantopaloglu/godot-mcp"
      ]
    }
  }
}
启动命令npx -y @tugcantopaloglu/godot-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npm@tugcantopaloglu/godot-mcp1.0.0

工具

154

收录的工具列表 · 更新于 2 周前

参数类型必填说明
projectPathstring是Godot 项目路径

详细介绍

godot_mcp_header

Godot MCP - 全面控制

MCP Server Made with Godot TypeScript MIT License

一款功能全面的模型上下文协议（MCP）服务，可让 AI 助手全面控制 Godot 游戏引擎。提供 157 个工具，涵盖网络、3D/2D 渲染、UI 控件、音效、动画树、文件 I/O、运行时代码执行、属性检查、场景操作、信号管理、物理、项目创建等功能。

致谢

本项目基于 Solomon Elias (Coding-Solo) 的 godot-mcp 构建并扩展。原项目提供了基础架构，包括 TypeScript MCP 服务、无头 GDScript 操作系统和基于 TCP 的运行时交互服务。感谢你出色的开源成果，让这一切成为可能！

更新内容（相较于原版的改进）

原版 godot-mcp 提供了 20 个工具，用于基本的项目管理和场景创建。本分支将其扩展至 157 个工具，主要新增内容如下：

3.1 版本新增
  • validate_script 自动加载解析 - 脚本验证现在会在 _initialize() 时通过 SceneTree 编译目标脚本（此时项目自动加载项已注册），而不是在 _init() 时使用 --check-only。引用自动加载单例不再产生误报的 Identifier not found 错误，同时仍可捕获真正的语法/类型错误。已通过构建一个脚本引用多个自动加载项的完整游戏进行验证。
  • manage_input_map 事件合并 - 向现有输入动作添加第二个按键时，现在会将其合并到该动作的 events 数组中（并对 physical_keycode 去重），而不是写入重复的 actionname= 行；此前这种情况会导致 project.godot 格式错误，并悄悄丢弃先前的按键绑定。
3.0 版本新增
  • .NET / C# 支持 - 创建 C# 项目脚手架并生成 C# 脚本（通过 create_project 并设置 dotnet: true，以及使用 create_csharp_script）；.csproj SDK 版本会与已安装的 Godot 版本保持一致。
  • GDScript 诊断 - 无需运行游戏即可检查脚本的语法和类型错误（使用 validate_script，以及对所有 Git 变更文件或整个项目文件执行检查的 validate_scripts）。
  • 修复无头场景操作和运行时交互服务中的正确性与健壮性问题（现在资源类型属性可以正常保留，重新设置父节点功能正常，运行时命令会按请求 ID 关联，且即使项目将警告视为错误，工具也能正常运行）。需要 Godot 4.4 或更高版本；已在最新的 Godot 4.7 上测试并确认可用。
运行时代码执行
  • game_eval - 在运行中的游戏内执行任意 GDScript 代码并返回结果
  • 完整支持异步 GDScript 代码的 await
  • 即使游戏已暂停也能运行（PROCESS_MODE_ALWAYS）
运行时节点检查与操作
  • game_get_property / game_set_property - 按路径读取/写入任意节点的任意属性
  • game_call_method - 使用参数调用任意节点上的任意方法
  • game_get_node_info - 全面检查节点：属性、信号、方法、子节点
  • game_instantiate_scene - 在运行中的游戏内动态添加场景
  • game_remove_node - 在运行时移除节点
  • game_change_scene - 在运行时切换场景
  • game_reparent_node - 在不同父节点之间移动节点
信号系统
  • game_connect_signal - 在运行时建立信号连接
  • game_disconnect_signal - 移除信号连接
  • game_emit_signal - 发出带参数的信号
动画与补间
  • game_play_animation - 控制 AnimationPlayer（播放、停止、暂停、列出）
  • game_tween_property - 使用可配置的缓动方式平滑地为属性制作动画
游戏控制与调试
  • game_pause - 暂停／取消暂停游戏
  • game_performance - FPS、帧时间、内存、对象数量、绘制调用
  • game_wait - 等待 N 帧（用于对时序敏感的操作）
  • game_get_nodes_in_group - 按组查询节点
  • game_find_nodes_by_class - 查找指定类的所有节点
无头场景操作（无需运行游戏）
  • read_scene - 解析任意 .tscn 文件，并以 JSON 格式获取完整节点树及其属性
  • modify_scene_node - 更改场景文件中的节点属性
  • remove_scene_node - 从场景文件中移除节点
  • attach_script - 将 GDScript 文件附加到场景中的节点
  • create_resource - 创建 .tres 资源文件（材质、主题等）
项目管理
  • read_project_settings - 将 project.godot 解析为结构化 JSON
  • modify_project_settings - 以编程方式更改项目设置
  • list_project_files - 按扩展名列出并筛选项目文件
文件 I/O
  • read_file / write_file / delete_file - 完整访问 Godot 项目内的文件系统
  • create_directory - 为脚本、场景、资源创建目录结构
错误与日志捕获
  • game_get_errors - 获取自上次调用以来新增的 push_error/push_warning 消息
  • game_get_logs - 获取运行中的游戏自上次调用以来新增的 print 输出
增强输入
  • game_key_hold / game_key_release - 按住按键以测试移动（WASD 等）
  • game_scroll - 鼠标滚轮事件
  • game_mouse_drag - 跨多帧在两点之间拖动
  • game_gamepad - 游戏手柄按钮和轴输入事件
项目创建与配置
  • create_project - 从头创建新的 Godot 项目（传入 dotnet: true 可搭建 .NET/C# 项目）
  • create_csharp_script - 在 Godot .NET 项目中创建 C# 脚本
  • manage_autoloads - 添加、移除或列出自动加载项
  • manage_input_map - 添加、移除或列出输入操作和按键绑定
  • manage_export_presets - 创建或修改导出预设配置
.NET / C# 支持
  • create_project 并传入 dotnet: true - 搭建 Godot .NET 项目（.csproj 使用与 Godot 版本匹配的 Godot.NET.Sdk，并包含 "C#" 功能标志）
  • create_csharp_script - 生成符合 C# 惯例的脚本（partial class，具有正确的 _Ready/_Process 重写签名）；类名会与文件名保持一致，以便 Godot 附加该脚本
  • get_project_info - 返回 isDotnet 字段
GDScript 诊断
  • validate_script - 在无头模式下检查单个 GDScript 文件的语法和类型错误，并返回 { valid, errors: [{ message, file, line }] }
  • validate_scripts - 批量验证所有经 git 更改的 .gd 文件（或整个项目），以便 Agent 在运行游戏前验证所做修改
摄像机、物理与音频
  • game_get_camera / game_set_camera - 查询和控制 2D/3D 摄像机
  • game_raycast - 发射物理射线（自动检测 2D 或 3D）
  • game_get_audio - 获取音频总线布局和正在播放的流
  • game_spawn_node - 在运行时创建带属性的任意节点类型
  • game_set_shader_param - 设置材质上的着色器参数
  • game_audio_play / game_audio_bus - 全面的音频播放和总线控制
  • game_navigate_path - 查询导航路径（2D/3D）
  • game_tilemap - 获取/设置 TileMapLayer 单元格
  • game_add_collision - 向物理体添加碰撞形状
  • game_environment - 配置后期处理（雾、辉光、SSAO、色调映射等）
  • game_manage_group - 将节点添加到组或从组中移除
  • game_create_timer - 以编程方式创建计时器节点
  • game_set_particles - 配置 GPUParticles2D/3D 属性和处理材质
  • game_create_animation - 创建包含值、方法、贝塞尔和音频轨道及关键帧的动画
  • export_project - 触发无头项目导出构建（适用于 CI/CD）
  • game_serialize_state - 将整个节点树状态保存/加载为 JSON
  • game_physics_body - 配置质量、速度、阻尼、摩擦和反弹
  • game_create_joint - 创建物理关节（销、弹簧、铰链、锥形、滑块）
  • game_bone_pose - 获取/设置骨架骨骼姿势，用于角色动画
  • game_ui_theme - 应用颜色、常量和字体大小主题覆盖
  • game_viewport - 创建/配置 SubViewport 节点
  • game_debug_draw - 绘制调试几何图形（线、球体、方框）
网络
  • game_http_request - 使用标头和正文发送 HTTP GET/POST/PUT/DELETE 请求
  • game_websocket - WebSocket 客户端连接/断开连接/发送消息
  • game_multiplayer - 创建 ENet 多人游戏服务器/客户端或断开连接
  • game_rpc - 调用或配置节点上的 RPC 方法
系统与窗口控制
  • game_script - 在运行时附加、分离节点脚本或获取其源代码
  • game_window - 获取/设置窗口大小、全屏状态、标题和位置
  • game_os_info - 获取平台、区域设置、屏幕、适配器和内存信息
  • game_time_scale - 获取/设置 Engine.time_scale 和计时信息
  • game_process_mode - 设置节点处理模式（可暂停/始终/禁用）
  • game_world_settings - 获取/设置重力、物理 FPS 和世界设置
高级信号与输入
  • game_list_signals - 列出节点上的所有信号及其连接
  • game_await_signal - 等待信号，可设置超时时间并返回参数
  • game_touch - 模拟触摸按下/释放/拖动和手势
  • game_input_state - 查询已按下的按键、鼠标位置和已连接的手柄
  • game_input_action - 管理运行时 InputMap 操作及其强度
3D 渲染与几何图形
  • game_csg - 创建/配置带布尔运算的 CSG 节点
  • game_multimesh - 创建/配置用于实例化的 MultiMeshInstance3D
  • game_procedural_mesh - 通过顶点数据使用 ArrayMesh 生成网格
  • game_light_3d - 创建/配置 3D 灯光（方向光/全向光/聚光灯）
  • game_mesh_instance - 使用基本网格创建 MeshInstance3D
  • game_gridmap - 设置/获取/清除 GridMap 单元格，并查询已使用的单元格
  • game_3d_effects - 创建 ReflectionProbe、Decal 或 FogVolume
  • game_gi - 创建/配置 VoxelGI 或 LightmapGI
  • game_path_3d - 创建 Path3D/Curve3D 并管理曲线点
  • game_sky - 创建/配置包含程序化天空/物理天空的 Sky
  • game_camera_attributes - 配置摄像机的景深、曝光和自动曝光
  • game_navigation_3d - 创建/配置 NavigationRegion3D 并进行烘焙
  • game_physics_3d - 执行 Area3D 查询和点/形状相交测试
2D 系统
  • game_canvas - 创建／配置 CanvasLayer 和 CanvasModulate
  • game_canvas_draw - 2D 绘图：线条／矩形／圆形／多边形／文本／清除
  • game_light_2d - 创建／配置 2D 光源和光遮挡器
  • game_parallax - 创建／配置 ParallaxBackground 和图层
  • game_shape_2d - 操作 Line2D／Polygon2D 的点
  • game_path_2d - 管理 Path2D／Curve2D 和 AnimatedSprite2D
  • game_physics_2d - Area2D 查询和 2D 点／形状相交检测
高级动画
  • game_animation_tree - 控制 AnimationTree 状态机跳转和参数
  • game_animation_control - 控制 AnimationPlayer 的跳转、队列、速度和信息
  • game_skeleton_ik - 启动／停止 SkeletonIK3D 并设置目标位置
高级音频
  • game_audio_effect - 添加／移除／配置音频总线效果
  • game_audio_bus_layout - 创建／移除／重新排序音频总线和路由
  • game_audio_spatial - 配置 AudioStreamPlayer3D 的空间属性
编辑器和项目工具
  • rename_file - 在项目中重命名或移动文件
  • manage_resource - 读取或修改 .tres／.res 资源文件
  • create_script - 根据模板创建 GDScript 文件
  • validate_script - 在无头模式下检查 GDScript 文件的语法／类型错误（无需运行）
  • validate_scripts - 批量检查 GDScript 文件：默认检查 git 变更的文件，也可检查所有文件
  • manage_scene_signals - 列出／添加／移除 .tscn 文件中的信号连接
  • manage_layers - 列出／设置项目中的命名图层定义
  • manage_plugins - 列出／启用／禁用编辑器插件
  • manage_shader - 创建或读取 .gdshader 文件
  • manage_theme_resource - 创建／读取／修改 Theme .tres 资源
  • set_main_scene - 在 project.godot 中设置主场景
  • manage_scene_structure - 在 .tscn 场景中重命名／复制／移动节点
  • manage_translations - 列出／添加／移除项目中的翻译文件
  • game_locale - 在运行时设置／获取区域设置并翻译字符串
UI 控件
  • game_ui_control - 设置 Control 的焦点、锚点、工具提示和鼠标过滤器
  • game_ui_text - 执行 LineEdit／TextEdit／RichTextLabel 文本操作
  • game_ui_popup - 显示／隐藏／弹出 Popup／Dialog／Window 节点
  • game_ui_tree - Tree 控件：获取／选择／折叠／添加／移除项目
  • game_ui_item_list - ItemList／OptionButton：获取／选择／添加／移除项目
  • game_ui_tabs - TabContainer／TabBar：获取／设置当前标签页
  • game_ui_menu - PopupMenu／MenuBar：添加／移除／获取菜单项
  • game_ui_range - 获取／设置 ProgressBar／Slider／SpinBox／ColorPicker
渲染和资源
  • game_render_settings - 获取／设置 MSAA、FXAA、TAA、缩放模式／比例
  • game_resource - 在运行时加载、保存或预加载资源
稳健性改进
  • 可重入保护 - 在异步操作期间防止并发处理命令
  • 完整类型转换 - 支持 Vector2／3、Color、Quaternion、Basis、Transform2D／3D、AABB、Rect2 以及所有打包数组类型
  • 智能属性类型检测 - 使用节点的 get_property_list() 自动转换类型
  • PackedArray 序列化 - 正确序列化为 JSON 数组，而非回退为字符串
  • 优雅的错误处理 - 缺少依赖项时，场景读取会回退到原始 .tscn 文本

全部 157 个工具

项目管理（7 个工具）
工具描述
launch_editor为项目启动 Godot 编辑器
run_project运行 Godot 项目并捕获输出
stop_project停止正在运行的项目
get_debug_output获取控制台输出和错误
get_godot_version获取已安装的 Godot 版本
list_projects在目录中查找 Godot 项目
get_project_info获取项目元数据
场景管理（7 个工具）
工具描述
create_scene使用根节点类型创建新场景
add_node向现有场景添加节点
load_sprite将纹理加载到 Sprite2D 节点
export_mesh_library将场景导出为 MeshLibrary
save_scene保存场景（可选变体路径）
get_uid获取文件的 UID（Godot 4.4+）
update_project_uids重新保存资源以更新 UID
无头场景操作（5 个工具）
工具描述
read_scene将完整场景树读取为 JSON
modify_scene_node修改场景文件中的节点属性
remove_scene_node从场景文件中移除节点
attach_script将 GDScript 附加到场景节点
create_resource创建 .tres 资源文件
项目设置（3 个工具）
工具描述
read_project_settings将 project.godot 解析为 JSON
modify_project_settings更改项目设置
list_project_files列出／筛选项目文件
运行时输入（4 个工具）
工具描述
game_screenshot捕获屏幕截图（base64 PNG）
game_click单击指定位置
game_key_press发送按键或输入动作
game_mouse_move移动鼠标
运行时检查（3 个工具）
工具描述
game_get_ui获取所有可见 UI 元素
game_get_scene_tree获取完整的场景树结构
game_get_node_info详细检查节点信息
运行时代码执行（1 个工具）
工具描述
game_eval执行任意 GDScript 并返回结果
运行时节点操作（7 个工具）
工具描述
game_get_property获取任意节点属性
game_set_property设置任意节点属性（自动转换类型）
game_call_method调用节点上的任意方法
game_instantiate_scene将 PackedScene 添加到运行中的场景树
game_remove_node从场景树中移除节点
game_change_scene切换到其他场景
game_reparent_node将节点移至新的父节点下
运行时信号（5 个工具）
工具描述
game_connect_signal将信号连接到方法
game_disconnect_signal断开信号连接
game_emit_signal发出带参数的信号
game_list_signals列出节点上的所有信号及其连接
game_await_signal等待信号，在超时后返回参数
运行时动画（2 个工具）
工具描述
game_play_animation控制 AnimationPlayer
game_tween_property使用缓动对属性进行补间
运行时实用工具（5 个工具）
工具描述
game_pause暂停／取消暂停游戏
game_performance获取 FPS、内存和绘制调用次数
game_wait等待 N 帧
game_get_nodes_in_group按组查询节点
game_find_nodes_by_class按类类型查找节点
文件 I/O（4 个工具）
工具描述
read_file从 Godot 项目中读取文本文件
write_file创建或覆盖文本文件
delete_file删除项目中的文件
create_directory在项目中创建目录
错误与日志捕获（2 个工具）
工具描述
game_get_errors获取自上次调用以来的新错误／警告
game_get_logs获取自上次调用以来的新打印输出
增强输入（8 个工具）
工具描述
game_key_hold按住按键（不会自动释放）
game_key_release释放已按住的按键
game_scroll鼠标滚轮事件
game_mouse_drag在 N 帧内拖动两个点之间的鼠标
game_gamepad手柄按钮或轴输入
game_touch模拟触摸按下／释放／拖动和手势
game_input_state查询已按下的按键、鼠标位置和已连接的手柄
game_input_action管理运行时 InputMap 操作及强度
项目创建（5 个工具）
工具描述
create_project创建新的 Godot 项目（支持通过 dotnet: true 使用 C#）
create_csharp_script在 Godot .NET 项目中创建 C# 脚本
manage_autoloads添加、移除或列出自动加载项
manage_input_map添加、移除或列出输入操作
manage_export_presets创建或修改导出预设
高级运行时（24 个工具）
工具描述
game_get_camera获取活动摄像机的位置／旋转／缩放
game_set_camera移动或旋转活动摄像机
game_raycast发射射线并返回碰撞结果
game_get_audio获取音频总线布局和正在播放的音频流
game_spawn_node在运行时创建任意类型的新节点
game_set_shader_param设置节点材质上的着色器参数
game_audio_play播放、停止或暂停 AudioStreamPlayer 节点
game_audio_bus设置音频总线的音量、静音或独奏
game_navigate_path查询两点之间的导航路径
game_tilemap获取或设置 TileMapLayer 节点中的单元格
game_add_collision向物理体节点添加碰撞形状
game_environment获取或设置环境和后期处理设置
game_manage_group将节点添加到组或从组中移除，或列出组
game_create_timer创建并配置 Timer 节点
game_set_particles配置 GPUParticles2D/3D 节点属性
game_create_animation创建带有轨道和关键帧的动画
game_serialize_state将节点树状态保存为 JSON 或从 JSON 加载
game_physics_body配置物理体属性（质量、速度）
game_create_joint在两个物理体之间创建物理关节
game_bone_pose获取或设置 Skeleton3D 节点上的骨骼姿势
game_ui_theme为 Control 节点应用主题覆盖
game_viewport创建或配置 SubViewport 节点
game_debug_draw在 3D 场景中绘制调试线条、球体或方框
构建与导出（1 个工具）
工具描述
export_project使用预设导出 Godot 项目
网络（4 个工具）
工具描述
game_http_request使用标头和请求正文发送 HTTP GET/POST/PUT/DELETE 请求
game_websocketWebSocket 客户端连接／断开连接／发送消息
game_multiplayer创建 ENet 多人游戏服务端／客户端，或断开连接
game_rpc调用或配置节点上的 RPC 方法
系统与窗口（6 个工具）
工具描述
game_script附加、分离节点脚本或获取其源代码
game_window获取／设置窗口大小、全屏状态、标题和位置
game_os_info获取平台、区域设置、屏幕、适配器和内存信息
game_time_scale获取／设置 Engine.time_scale 和时间信息
game_process_mode设置节点处理模式（可暂停／始终／禁用）
game_world_settings获取／设置重力、物理 FPS 和世界设置
3D 渲染与几何体（13 个工具）
工具描述
game_csg使用布尔运算创建/配置 CSG 节点
game_multimesh创建/配置用于实例化的 MultiMeshInstance3D
game_procedural_mesh根据顶点数据通过 ArrayMesh 生成网格
game_light_3d创建/配置 3D 灯光（方向光/全向光/聚光灯）
game_mesh_instance使用基本网格创建 MeshInstance3D
game_gridmap设置/获取/清除 GridMap 单元格，并查询已使用的单元格
game_3d_effects创建 ReflectionProbe、Decal 或 FogVolume
game_gi创建/配置 VoxelGI 或 LightmapGI
game_path_3d创建 Path3D/Curve3D 并管理曲线点
game_sky使用程序化天空/物理天空创建/配置 Sky
game_camera_attributes配置相机的景深、曝光和自动曝光
game_navigation_3d创建/配置 NavigationRegion3D 并进行烘焙
game_physics_3dArea3D 查询以及点/形状相交测试
2D 系统（7 个工具）
工具描述
game_canvas创建/配置 CanvasLayer 和 CanvasModulate
game_canvas_draw2D 绘制：线条/矩形/圆形/多边形/文本/清除
game_light_2d创建/配置 2D 灯光和灯光遮挡器
game_parallax创建/配置 ParallaxBackground 和图层
game_shape_2d操作 Line2D/Polygon2D 的点
game_path_2d管理 Path2D/Curve2D 和 AnimatedSprite2D
game_physics_2dArea2D 查询以及 2D 点/形状相交测试
高级动画（3 个工具）
工具描述
game_animation_tree控制 AnimationTree 状态机跳转和参数
game_animation_control控制 AnimationPlayer 的跳转/队列/速度/信息
game_skeleton_ik启动/停止 SkeletonIK3D 并设置目标位置
高级音频（3 个工具）
工具描述
game_audio_effect添加/移除/配置音频总线效果
game_audio_bus_layout创建/移除/重新排序音频总线并配置路由
game_audio_spatial配置 AudioStreamPlayer3D 的空间属性
编辑器与项目工具（14 个工具）
工具描述
rename_file重命名或移动项目中的文件
manage_resource读取或修改 .tres/.res 资源文件
create_script根据模板创建 GDScript 文件
validate_script检查 GDScript 文件的语法/类型错误（无头模式）
validate_scripts批量检查 GDScript 文件（默认检查 git 变更的文件，也可检查全部文件）
manage_scene_signals列出/添加/移除 .tscn 文件中的信号连接
manage_layers列出/设置项目中的命名图层定义
manage_plugins列出/启用/禁用编辑器插件
manage_shader创建或读取 .gdshader 文件
manage_theme_resource创建/读取/修改 Theme .tres 资源
set_main_scene设置 project.godot 中的主场景
manage_scene_structure重命名/复制/移动 .tscn 场景中的节点
manage_translations列出/添加/移除项目中的翻译文件
game_locale设置/获取区域设置并在运行时翻译字符串
UI 控件（8 个工具）
工具描述
game_ui_control设置 Control 的焦点、锚点、工具提示和鼠标筛选
game_ui_textLineEdit/TextEdit/RichTextLabel 文本操作
game_ui_popup显示/隐藏/弹出 Popup/Dialog/Window 节点
game_ui_treeTree 控件：获取/选择/折叠/添加/移除项目
game_ui_item_listItemList/OptionButton：获取/选择/添加/移除项目
game_ui_tabs获取/设置 TabContainer/TabBar 的当前选项卡
game_ui_menu添加/移除/获取 PopupMenu/MenuBar 菜单项
game_ui_range获取/设置 ProgressBar/Slider/SpinBox/ColorPicker 的值
渲染与资源（2 个工具）
工具描述
game_render_settings获取/设置 MSAA、FXAA、TAA、缩放模式/比例
game_resource运行时资源加载、保存或预加载

要求

  • Godot Engine 4.4 或更高版本（无头操作脚本和 UID 功能需要 4.4+）；已使用最新的 Godot 4.7 测试并确认可正常运行
  • （可选）.NET SDK 8.0+ 和 Godot .NET（C#）版本，仅当使用 create_project 的 dotnet: true 标志或 create_csharp_script 时需要
  • Node.js >= 18.0.0
  • 支持 MCP 的 AI 助手（Claude Code、Cline、Cursor 等）

安装

git clone https://github.com/tugcantopaloglu/godot-mcp.git
cd godot-mcp
npm install
npm run build

配置

Claude Code

将以下内容添加到 Claude Code MCP 设置中：

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "GODOT_PATH": "/path/to/godot",
        "DEBUG": "true"
      }
    }
  }
}
Cline（VS Code）

将以下内容添加到 Cline MCP 设置（cline_mcp_settings.json）中：

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "disabled": false
    }
  }
}
Cursor

在项目中创建 .cursor/mcp.json：

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"]
    }
  }
}

运行时工具设置

要使用 game_* 运行时工具，Godot 项目需要配置 MCP 交互服务器自动加载项。将 build/scripts/mcp_interaction_server.gd 复制到项目中，并将其注册为自动加载项：

  1. 将 build/scripts/mcp_interaction_server.gd 复制到项目的脚本文件夹
  2. 在 Godot 中：项目 > 项目设置 > 自动加载
  3. 添加该脚本，并将名称设为 McpInteractionServer

游戏运行时，服务器会监听 127.0.0.1:9090，并通过 TCP 接收 JSON 命令。

环境变量

变量描述
GODOT_PATHGodot 可执行文件的路径（覆盖自动检测结果）
DEBUG设为 "true" 可启用详细的服务器端日志记录
GODOT_MCP_ALLOWED_DIRS可选。将所有项目工具、项目发现功能和导出目标限制在这些根目录内。Windows 上使用 ; 或 , 分隔，其他系统上使用 : 或 , 分隔。检查访问权限前会解析现有符号链接。未设置时，允许任何项目根目录。

文件和场景路径必须位于其项目目录内，包括符号链接下的路径。 这些检查涵盖 MCP 工具参数。运行时评估和生成的脚本会使用 Godot 进程账户的权限运行，因此执行不受信任的代码时，请使用独立账户或容器。

运行时日志保留

game_get_logs 和 game_get_errors 接受可选的 cursor 和 limit 参数。默认每页 200 行，最多 500 行。响应包含 nextCursor、hasMore 和 dropped。将 nextCursor 传回即可从同一位置继续。未提供游标的调用会从上次调用的位置继续。每个流会保留最新的 2,000 行，每行最多 4,096 个字符。如果游标早于已保留的输出，dropped 将为 true。get_debug_output 会返回保留的流及其起始偏移量。

贡献者验证

开发和 CI 要求 Node.js 22.12 或更高版本。服务器运行时的版本要求仍以 package.json 中指定的版本为准。

npm ci
npm test
npm audit --audit-level=moderate

CI 在 Node.js 22 和 24 上运行，不会发布软件包或部署服务。 npm test 会先构建服务器，以确保可执行入口测试使用最新代码。 测试包括通过 SDK 内存传输发送真实 MCP 请求、文件系统边界检查、符号链接越界检查、项目脚手架、架构验证和游标分页。运行实际 Godot 项目仍属于集成检查，需要安装引擎。将 GODOT_SMOKE_PATH 设为其控制台可执行文件的完整路径，即可启用临时项目无头冒烟测试。该测试会创建项目、创建并编辑场景、通过 MCP 读取场景，并保存第二个场景。测试结束后会删除临时文件。

架构

该服务使用两种通信通道：

  1. 无头 CLI - 用于不需要运行游戏的操作（场景读取、修改、资源创建）。通过 --headless --script godot_operations.gd <operation> <json_params> 运行 Godot。

  2. TCP 套接字 - 用于与正在运行的游戏进行运行时交互。mcp_interaction_server.gd 自动加载脚本会监听端口 9090，并处理 TypeScript MCP 服务发送的 JSON 命令。

源码布局
路径描述
src/index.tsMCP 服务、工具定义及所有处理程序
src/utils.ts纯工具函数（参数映射、验证、错误辅助函数）
src/scripts/godot_operations.gd无头 GDScript 操作运行器
src/scripts/mcp_interaction_server.gdTCP 交互服务自动加载脚本
tests/Vitest 测试套件

测试

项目使用 Vitest，包含 5 个文件中的 446 项测试：

文件测试数覆盖内容
tests/utils.test.ts31参数映射、规范化、路径验证、错误响应、版本检测
tests/tool-definitions.test.ts163定义的全部 155 个工具、有效的架构、唯一名称、长度小于 80 个字符的描述
tests/handlers.test.ts225游戏命令参数转换、必需参数验证、无头操作路径检查、源码结构
tests/dotnet.test.ts20.NET 功能标志、.csproj 生成、C# 脚本模板生成、标识符验证
tests/validate-script.test.ts12GDScript 诊断解析 + git 已更改文件收集
npm test          # run once
npm run test:watch  # watch mode

示例提示词

"Run my Godot project and check for errors"

"Eval this in my running game: return get_tree().current_scene.name"

"Get the player's position in the running game"

"Set the player's health to 100"

"Read the test_level.tscn scene and show me the node tree"

"Change the player's speed property in the player.tscn scene file"

"List all .gd files in my project"

"Connect the enemy's 'died' signal to the game manager's 'on_enemy_died' method"

"Tween the camera's position to (0, 10, -5) over 2 seconds with ease-out"

"Get performance metrics - what's my FPS and draw call count?"

"Pause the game and take a screenshot"

"Find all CharacterBody3D nodes in the scene"

"Create a new Godot project called 'MyGame' and write a player script"

"Create a new C# (.NET) Godot project and add a CharacterBody2D script"

"Validate player.gd for errors"

"Check all my changed GDScript files for syntax errors before I run the game"

"Hold down the W key for 2 seconds to test walking"

"Cast a ray from the player downward to check for ground"

"Get the camera position and move it to look at the player"

"Show me the latest error messages from the running game"

许可证

本项目采用 MIT 许可证授权 - 详情请参阅 LICENSE 文件。

致谢

  • 原始项目：godot-mcp，由 Solomon Elias (Coding-Solo) 开发 - 提供了基础 MCP 服务架构、无头操作系统和 TCP 交互框架
  • 扩展者：Tugcan Topaloglu - 将工具扩展至 157 个，涵盖网络、3D/2D 渲染、UI 控件、音频效果、动画树、文件 I/O、运行时代码执行、节点操作、信号、项目创建、摄像机控制、物理以及全面的类型转换

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。