Godot MCP

godot-mcp — 适用于 Godot 4 的纯 Python FastMCP 服务

适用于 Godot 4 的 无需 Node.js 的模型上下文协议服务——从 Coding-Solo/godot-mcp 和 youichi-uda/godot-mcp-pro 移植而来，使用官方的 FastMCP 框架以纯 Python 实现。通过 uvx 运行，内存占用极低。

快速开始

你可以在计算机上的任意位置，通过标准输入/输出（stdio）立即调用此服务，使用 uvx 即可，无需手动克隆文件或配置虚拟环境：

# Run globally via uvx from PyPI (Bypasses local setup completely)
GODOT_PATH=/path/to/godot4 uvx --from godot-mcp-uvx godot-mcp

# Local development installation (For active contributors)
git clone https://github.com/jxlee007/godot_mcp
cd godot_mcp
uv tool install --editable .

MCP 客户端配置

将以下配置块直接添加到全局客户端环境配置文件中（例如 ~/.gemini/antigravity-cli/settings.json 或 Claude / Cline 设置）：

{
  "mcpServers": {
    "godot_render": {
      "command": "uvx",
      "args": [
        "--from",
        "godot-mcp-uvx",
        "godot-mcp"
      ],
      "env": {
        "GODOT_PATH": "/path/to/godot4",
        "DEBUG": "false"
      }
    }
  }
}

环境变量

变量	描述
GODOT_PATH	Godot 4 可执行文件的路径（未设置时会自动检测）
DEBUG	设置为 "true" 时启用详细的 stderr 日志

工具（共 28 个）

核心运行时（14 个）

工具	描述
get_godot_version	返回已安装的 Godot 版本
launch_editor	打开项目的 Godot 编辑器
run_project	以调试模式运行项目并捕获输出
get_debug_output	读取运行中项目的 stdout/stderr
stop_project	终止运行中的项目并返回最终输出
list_projects	在目录中查找 Godot 项目
get_project_info	获取元数据、文件数量和版本
create_scene	通过 GDScript 创建新的 .tscn 文件
add_node	向现有场景添加节点
load_sprite	将纹理加载到 Sprite2D/TextureRect 上
export_mesh_library	将 .tscn 导出为 MeshLibrary .res
save_scene	保存场景文件或另存为新文件
get_uid	获取 Godot 4.4+ 资源的 UID
update_project_uids	重新保存所有资源以重新生成 UID

动画文本处理流水线（4 个）

工具	描述
quantize_animation_keyframes	将时间戳舍入到固定的 fps 间隔（呈现 12/24 fps 动画风格）
set_animation_interpolation_mode	批量切换缓动方式：线性、三次、最近邻/阶梯式
stitch_animation_library	将外部 .glb/.tres 动画片段合并到主 AnimationLibrary 中
generate_track_filter	为上半身/下半身分离生成 AnimationNodeBlendFilter

AnimationTree 蓝图设计（3 个）

工具	描述
generate_state_machine	将 AnimationNodeStateMachine 注入 .tscn 文件
compile_state_transitions	写入带条件的状态转换箭头
calculate_blend_space_2d	为定向移动生成 2D 混合空间

摄像机与电影效果（3 个）

工具	描述
generate_bezier_camera_path	生成具有张力控制的 Catmull-Rom 贝塞尔 Path3D + PathFollow3D + Camera3D
inject_lookat_tracking	为 Camera3D 生成 LookAt 跟踪 GDScript
build_camera_switcher_timeline	编写可按时间戳切换 Camera3D.current 的 Animation

NPR 材质与着色器（2 个）

工具	描述
batch_shader_uniforms	批量覆盖所有 .tres 文件中的 shader_parameter/*
remap_texture_channels	将纹理接入材质属性槽

流水线自动化（2 个）

工具	描述
toggle_movie_maker	编辑 project.godot 以启用/禁用 Movie Maker 模式
run_headless_diagnostics	通过 Godot CLI 验证导入、UID 和着色器入口点

架构

src/godot_mcp/
├── __init__.py
├── server.py              # FastMCP app — all 28 tools
└── scripts/
    └── godot_operations.gd  # Bundled GDScript engine (preserved untouched)

两种运行模式：

1. 子进程桥接 — 核心的 14 个工具通过 subprocess.run() 无头调用 godot_operations.gd
2. 文本操作 — pro-port 的 14 个工具仅使用 Python 标准库 re，以纯文本形式解析/写入 .tscn、.tres 和 project.godot 文件

要求

• Python 3.10+
• 已安装 Godot 4.x（设置 GODOT_PATH 或确保其位于 $PATH 中）
• uv 或 pip

许可证

MIT