Minimal Godot MCP

最小godot-mcp

MCP服务器将Godot的本地LSP桥接到AI编码助手，以进行GDScript验证

](https://www.npmjs.com/package/@ryanmazzolini/minimal-godot-mcp)  ](https://nodejs.org/)

目录

• 快速开始
• 配置
• 特性
• MCP工具
• 发展
• 故障排除
• 配合良好
• 参考文献
• 许可证

快速开始

先决条件： 启用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

所有可选的默认值适用于大多数设置。

将这些作为 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

• 语言服务器协议 （语言服务器协议，实线）：始终连接以进行诊断
• 目的地交货 （调试适配器协议，虚线）：延迟连接时 get_console_output 以跑步场景调用

另请参见：

• Godot外部编辑器设置

从源头构建

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

贡献

1. 跑 npm run format && npm test 在提交之前
2. 使用真实的Godot项目进行测试
3. 将范围集中在诊断上

故障排除

看 docs/故障排除.md 用于连接问题、缺少诊断和调试日志记录。

配合良好

这两台服务器是互补的，可以并行运行。

参考文献

• 模型上下文协议 -协议规范
• Godot LSP -语言服务器设置

许可证

麻省理工学院-见 许可证