A
licenseC
qualityA
maintenanceAn MCP server providing AI assistants with 149 tools to fully control the Godot game engine, including runtime code execution, scene manipulation, physics, audio, networking, animation, and more.
100
92 npm
449
MIT
Godot MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Godot MCPAdd a CharacterBody2D node"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Godot MCP — AI 控制 Godot 编辑器
让 Cursor / Claude 直接操控 Godot 4 编辑器和运行中的游戏：建场景、写脚本、连信号、配粒子、调物理、测游戏……
151 个 MCP 工具，覆盖编辑器操作（port 9500）和游戏运行时（port 9501）。
架构
Cursor / Claude
│ MCP stdio
▼
Python MCP Server (server.py)
│ │
│ TCP JSON │ TCP JSON
│ port 9500 │ port 9501
▼ ▼
Godot Editor Plugin MCPRuntime Autoload
(plugin.gd) (mcp_runtime.gd)
│ │
▼ ▼
EditorInterface API Running Game Sceneport 9500：编辑器常驻，只要 Godot 开着就可以连
port 9501：游戏运行时才可用，按 F5 启动游戏后连接
Related MCP server: AI-godot-mcp
环境要求
Godot 4.2+（依赖静态 EditorInterface API）
Python 3.10+
pip
安装步骤
第一步：安装 Godot 插件
将 godot_plugin/addons/godot_mcp/ 整个文件夹复制到你的 Godot 项目根目录：
your_godot_project/
└── addons/
└── godot_mcp/
├── plugin.cfg
├── plugin.gd
└── mcp_runtime.gd然后在 Godot 中启用插件：
项目 → 项目设置 → 插件 → Godot MCP → 勾选「启用」
启用后左侧 Dock 出现 🤖 Godot MCP 状态面板，显示 ⏳ Waiting on port 9500…
第二步：安装 Python 依赖
cd godot-mcp
pip install -r requirements.txt第三步：配置 Cursor
在项目根目录创建或编辑 .cursor/mcp.json：
{
"mcpServers": {
"godot-mcp": {
"command": "python",
"args": ["D:/path/to/godot-mcp/mcp_server/server.py"]
}
}
}路径改成你本机的实际路径，Windows 用正斜杠或双反斜杠均可。
重启 Cursor，打开 Godot 项目，状态面板变为 ✅ Connected 即可。
工具一览（151 个）
连接 & 元信息
工具 | 说明 |
| 测试编辑器连接，返回版本和工具总数 |
| 测试游戏运行时连接 |
项目管理
工具 | 说明 |
| 项目名、版本、主场景、Godot 版本 |
| 文件树，可指定路径和深度 |
| 按名称或扩展名搜索文件 |
| 读取 ProjectSettings 键值 |
| 修改 ProjectSettings 键值 |
|
|
| Godot UID → |
场景管理
工具 | 说明 |
| 当前场景完整节点树 |
| 所有已打开的场景 |
| 打开指定场景 |
| 保存当前场景 |
| 新建场景文件 |
| 运行场景（当前或指定） |
| 停止游戏 |
| 实例化子场景到当前场景 |
| 读取 .tscn 文件原文 |
节点操作
工具 | 说明 |
| 新建节点 |
| 删除节点（含子节点） |
| 重命名节点 |
| 获取节点所有属性 |
| 设置节点属性（支持 Vector/Color 等类型） |
| 移动节点到新父节点 |
| 深拷贝节点 |
| 查看节点信号和现有连接 |
| 连接信号到方法 |
| 断开信号连接 |
| 添加/移除节点分组 |
| 获取指定分组所有节点 |
| 设置 Control 锚点预设（ |
| 创建 Resource 并赋给节点属性 |
脚本操作
工具 | 说明 |
| 新建 GDScript 文件 |
| 读取脚本内容 |
| 编辑脚本（全量替换或搜索替换） |
| 将脚本挂到节点 |
| 列出项目所有 .gd 文件 |
| 检测脚本语法错误 |
| 列出脚本编辑器中已打开的脚本 |
动画
工具 | 说明 |
| 列出 AnimationPlayer 中所有动画 |
| 新建动画剪辑 |
| 获取动画轨道和关键帧详情 |
| 添加动画轨道 |
| 插入关键帧 |
| 删除动画 |
AnimationTree
工具 | 说明 |
| 创建 AnimationTree 节点（含 StateMachine） |
| 查看状态机结构 |
| 添加状态 |
| 删除状态 |
| 添加状态转换 |
| 删除状态转换 |
| 配置 BlendTree 中的节点 |
| 设置 AnimationTree 参数值 |
TileMap
工具 | 说明 |
| 设置单个格子的 tile |
| 读取单个格子的 tile 数据 |
| 用同一 tile 填充矩形区域 |
| 清除整个 TileMap 或指定层 |
| 获取 TileMap 层和 TileSet 信息 |
| 获取所有非空格子坐标 |
3D 场景
工具 | 说明 |
| 添加 MeshInstance3D（含基础网格和材质） |
| 添加 DirectionalLight3D / OmniLight3D / SpotLight3D |
| 设置 3D 节点材质颜色和属性 |
| 创建 WorldEnvironment（天空、雾、辉光、SSAO） |
| 添加 Camera3D（FOV、近/远裁剪面） |
| 添加 GridMap 节点 |
物理
工具 | 说明 |
| 为节点添加 CollisionShape2D/3D（box/circle/capsule） |
| 添加 RayCast2D/3D（正值 length = 向下） |
| 配置 CharacterBody/RigidBody 参数 |
| 设置碰撞层和遮罩位掩码 |
| 读取碰撞层和遮罩 |
| 查看节点的所有碰撞形状 |
粒子系统
工具 | 说明 |
| 创建 GPUParticles2D/3D |
| 配置 ParticleProcessMaterial 参数 |
| 设置颜色渐变 |
| 应用预设效果（fire/smoke/rain/snow/sparks） |
| 读取粒子系统当前配置 |
导航
工具 | 说明 |
| 创建 NavigationRegion2D/3D（自动初始化 NavigationPolygon/Mesh） |
| 烘焙导航网格 |
| 添加 NavigationAgent2D/3D |
| 设置导航层位掩码 |
| 读取导航节点配置 |
音频
工具 | 说明 |
| 添加 AudioStreamPlayer/2D/3D |
| 新建音频总线 |
| 将音频播放器分配到指定总线 |
| 添加音效（reverb/delay/compressor/limiter/eq/chorus/distortion） |
| 获取所有总线和音效布局 |
| 读取音频播放器配置 |
主题 & UI
工具 | 说明 |
| 新建 .theme 资源文件 |
| 设置颜色条目 |
| 设置整数常量（边距、间距等） |
| 设置字体大小 |
| 设置 StyleBoxFlat（圆角、边框、颜色） |
| 读取 Theme 全部条目 |
Shader
工具 | 说明 |
| 新建 .gdshader 文件 |
| 读取 shader 源码 |
| 修改 shader 源码 |
| 给节点创建并挂载 ShaderMaterial |
| 设置 shader uniform 参数值 |
| 读取 shader 所有参数 |
资源管理
工具 | 说明 |
| 新建 .tres 资源文件 |
| 读取资源属性 |
| 修改资源属性并保存 |
批量操作 & 重构
工具 | 说明 |
| 在当前场景中查找指定类型的所有节点 |
| 批量设置同类节点的属性 |
| 查找指定信号的所有连接 |
| 查找节点在脚本中的引用 |
| 列出场景依赖的所有资源 |
| 跨场景批量修改节点属性 |
代码分析
工具 | 说明 |
| 项目文件数、节点数、脚本数统计 |
| 查找项目中未被引用的资源文件 |
| 分析场景节点数和脚本密度 |
| 在脚本中搜索符号引用 |
| 检测脚本 extends 循环依赖 |
| 分析场景中的信号流图 |
性能监控
工具 | 说明 |
| 读取 FPS、内存、Draw Call、物理对象数等 |
| 读取编辑器帧率和场景节点数 |
导出
工具 | 说明 |
| 列出所有导出预设 |
| 获取导出预设详细配置 |
| 生成导出 CLI 命令（需手动执行） |
编辑器工具
工具 | 说明 |
| 设置项目主场景 |
| 截图编辑器屏幕（base64 PNG） |
| 重新扫描项目文件系统 |
| 清除 Output 面板（打印分隔线） |
| 热重载指定插件 |
| 在编辑器上下文中执行 GDScript 代码 |
| 截图对比（save_reference → compare） |
游戏运行时工具（需先按 F5 启动游戏）
输入模拟
工具 | 说明 |
| 模拟键盘按键 |
| 模拟鼠标点击 |
| 模拟鼠标移动 |
| 模拟 InputMap 动作 |
| 按时间顺序执行一组输入事件 |
输入录制与回放
工具 | 说明 |
| 开始录制玩家输入 |
| 停止录制，返回事件列表 |
| 回放录制内容（支持变速） |
运行时场景检查
工具 | 说明 |
| 获取运行中的场景树 |
| 读取运行中节点属性 |
| 修改运行中节点属性 |
| 在游戏上下文中执行 GDScript |
| 截取游戏画面（base64 PNG） |
| 按间隔捕获多帧截图 |
| 采样监控节点属性变化曲线 |
| 按文字查找 UI 元素（Label/Button） |
| 点击指定文字的按钮 |
| 等待节点出现（超时返回失败） |
| 批量读取多个节点的属性 |
| 找出挂了指定脚本的所有节点 |
| 查看 Autoload 单例信息 |
测试 & QA
工具 | 说明 |
| 按步骤执行测试（支持异步命令） |
| 断言节点属性值（记入测试报告） |
| 断言屏幕上存在某段文字 |
| 随机输入压力测试 |
| 获取本次会话的全部断言结果 |
使用示例
在 Cursor 对话框中直接描述需求：
帮我创建一个 2D 平台跳跃游戏：
1. 创建主场景 res://game.tscn，根节点为 Node2D
2. 添加 CharacterBody2D 命名 Player
3. 给 Player 添加 Sprite2D 和 CollisionShape2D（圆形，半径24）
4. 创建 res://player.gd 实现 WASD 移动和跳跃
5. 将脚本挂到 Player，设为主场景并运行运行游戏，录制一段操作，然后用回放功能做回归测试：
1. start_recording 开始录制
2. （手动操作几秒）
3. stop_recording 保存操作序列
4. replay_recording 验证行为一致扩展开发
添加新的编辑器命令
plugin.gd — 在 _build_handlers() 字典里注册：
"my_command": _cmd_my_command,然后实现函数：
func _cmd_my_command(p: Dictionary) -> Dictionary:
var param = p.get("param", "default")
# ... 逻辑 ...
EditorInterface.save_scene() # 如果修改了场景节点
return {"result": "value"}server.py — 添加 MCP 工具：
@mcp.tool()
def my_tool(param: str) -> str:
"""工具描述（AI 会读这段来决定何时调用）"""
return _e("my_command", {"param": param})添加游戏运行时命令
在 mcp_runtime.gd 的 _build_handlers() 中注册，如果函数内含 await，还需要将命令名加入 _handle() 里的 _ASYNC_CMDS 列表。
常见问题
Q: 连接失败，显示 ConnectionRefusedError
确保 Godot 已打开且插件已启用，状态面板显示
⏳ Waiting on port 9500…
Q: 运行时工具提示 "Game is not running"
在 Godot 中按 F5 启动游戏，然后重试
Q: 修改了节点但场景没变
执行
save_scene手动保存，或检查对应工具是否返回了_error
Q: export_project 没有真正导出文件
该工具返回等效 CLI 命令，在项目目录下手动执行即可（编辑器插件无法安全运行子进程）
Q: 插件报 port 9500 already in use
已有另一个 MCP server 占用端口，关掉旧进程，或修改
plugin.gd的EDITOR_PORT常量
Q: 在 Godot 4.0/4.1 上报错
需要 Godot 4.2+，
EditorInterface静态类 API 在 4.2 才完整稳定
This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo issues
Related MCP Connectors
65+ AI tools as MCP: research, write, code, scrape, translate, RAG, agent memory, workflows
Free public MCP for AI agents — 193 tools, 44 workflows. No API key.
100+ MCP tools for AI agents: content metadata, trade intelligence, business-expertise analysis.
Generate game-ready 3D models, textures, and audio from natural language, over MCP.
Related MCP Servers
- AlicenseCqualityAmaintenanceEnables AI-driven game development by providing MCP tools to interact with the Godot editor, including scene editing, node manipulation, script attachment, and scene execution.2827 npmMIT
- AlicenseCqualityAmaintenanceGodot MCP connects AI assistants directly to the Godot editor, exposing 300+ tools for scene construction, node manipulation, runtime inspection, input recording, physics setup, animation authoring, and more.10072 npm20MIT
- AlicenseBqualityBmaintenanceThis MCP server allows AI assistants to control the Godot editor and running games, enabling scene creation, script editing, input simulation, and gameplay testing through 174 tools.100220 npmMIT