使用说明
最小godot-mcp
MCP服务器将Godot的本地LSP桥接到AI编码助手，以进行GDScript验证
目录
快速开始
先决条件： 启用LSP的Node.js 22+、Godot 3.2+或4.x
配置您的MCP客户端以运行服务器 npx （见以下示例）。打开项目启动Godot，MCP客户端将自动连接。
配置
MCP客户端设置
Claude Code
增添 ~/.claude.json:
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "@ryanmazzolini/minimal-godot-mcp"]
}
}
}
Cursor
增添 .cursor/mcp.json 在您的项目中：
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "@ryanmazzolini/minimal-godot-mcp"]
}
}
}
Other MCP Clients
配置您的客户端以运行：
npx -y @ryanmazzolini/minimal-godot-mcp
Advanced Configuration
所有可选的默认值适用于大多数设置。
| 变量 | 描述 | 默认值 |
|---|---|---|
GODOT_LSP_PORT |
覆盖LSP端口 | 尝试6007、6005、6008 |
GODOT_WORKSPACE_PATH |
Godot项目路径 | 从cwd自动检测到 |
GODOT_DAP_PORT |
覆盖DAP端口 | 尝试6006、6010 |
GODOT_DAP_BUFFER_SIZE |
缓冲区的最大控制台条目数 | 1000 |
将这些作为 env 在MCP客户端配置中：
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "@ryanmazzolini/minimal-godot-mcp"],
"env": {
"GODOT_WORKSPACE_PATH": "/path/to/your/godot/project"
}
}
}
}
特性
- 零配置LSP -使用Godot的原生语言服务器，无需插件
- 快速诊断 -单文件检查快速返回
- 占地面积最小 -轻量级响应，最大限度地减少令牌使用
- 弹性连接 -处理Godot自动重启
- 工作区扫描 -批量检查全部
.gd项目中的文件
MCP工具
get_diagnostics
检查单个GDScript文件是否有错误。
// Input
{ "file_path": "/path/to/script.gd" }
// Output
{
"diagnostics": {
"/path/to/script.gd": [
{ "line": 5, "column": 14, "severity": "error", "message": "Expected identifier", "code": "parse-error" }
]
}
}
scan_workspace_diagnostics
扫描所有 .gd 工作区中的文件（不包括 addons/ 和 .godot/).
// Input
{}
// Output
{
"files_scanned": 150,
"files_with_issues": 3,
"scan_time_seconds": 1.5,
"diagnostics": { ... }
}
get_console_output
从Godot调试会话获取控制台输出。需要运行场景（Godot中的F5）。
// Input (all optional)
{
"limit": 50,
"category": "console",
"since": 1706000000000
}
// Output
{
"entries": [
{ "timestamp": 1706000001234, "category": "console", "message": "Player spawned", "source": "/project/player.gd", "line": 42 }
],
"total_buffered": 150
}
类别： console （打印报表）， stdout, stderr （错误/警告）。
clear_console_output
清除控制台输出缓冲区。
// Input
{}
// Output
{ "cleared": true }
发展
建筑学
flowchart LR
MCP[MCP Client] <-->|stdio| Server[minimal-godot-mcp]
Server <-->|LSP :6007| Godot[Godot Editor]
Server <-.->|DAP :6006| Godot
另请参见：
从源头构建
先决条件： npm 12.0.1，支持Node.js版本(^22.22.2, ^24.15.0，或 >=26)
git clone https://github.com/ryanmazzolini/minimal-godot-mcp.git
cd minimal-godot-mcp
npm install && npm run build
然后使用 node /path/to/minimal-godot-mcp/dist/index.js 而不是 npx 在您的MCP客户端配置中。
命令
npm test # Run tests
npm run lint # ESLint + Prettier
npm run build # Compile TypeScript
贡献
- 跑
npm run format && npm test提交前 - 使用真实的Godot项目进行测试
- 将范围集中在诊断上
故障排除
看 docs/故障排除.md 用于连接问题、缺少诊断和调试日志记录。
配合良好
戈多特·麦克普 通过 @卫星电离层 通过Godot插件提供运行时控制、场景操作、屏幕截图、堆栈跟踪和直接编辑器交互。这个项目处理LSP和DAP端——诊断和控制台输出，不需要插件。
这两台服务器是互补的，可以并行运行。
参考文献
许可证
麻省理工学院-见 许可证
