Minimal Godot MCP

🚀 minimal-godot-mcp

轻量级MCP服务器，将Godot LSP与MCP客户端连接起来，用于GDScript验证

本项目旨在以最小的开销提供Godot诊断信息。通过它，你可以在Claude、Cursor和其他MCP客户端中即时获得GDScript语法反馈，无需切换到Godot，也无需安装自定义插件，它只是一个连接到Godot原生LSP的轻量级桥梁。

🚀 快速开始

前提条件

• Node.js 24+
• 启用LSP的Godot 3.2+ 或 4.x版本

安装设置

⚠️ 重要提示

该软件包尚未发布到npm。目前，请克隆项目并在本地进行构建。

# 克隆并构建项目
git clone https://github.com/ryanmazzolini/minimal-godot-mcp.git
cd minimal-godot-mcp
npm install
npm run build

# 启动Godot编辑器并打开你的项目

将你的MCP客户端（例如Claude Code）配置为使用本地构建的版本：

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

💡 使用建议

有关环境变量和特定客户端的示例，请参阅配置部分。

重启你的MCP客户端，然后开始编辑 .gd 文件吧✨

✨ 主要特性

• 🔌 零配置LSP集成：使用Godot的原生语言服务器（无需插件，无需额外依赖）
• ⚡ 快速诊断：单文件检查在1秒内返回结果
• 📦 最小占用：内存占用小于10MB，核心实现代码少于200行
• 💬 低上下文开销：轻量级响应，最大限度减少AI令牌使用
• 🔄 稳定连接：自动处理Godot重启和重新连接
• 🤝 兼容性好：与godot-vscode-plugin和其他LSP客户端兼容
• 🌐 工作区扫描：可选的批量检查所有 .gd 文件

Claude Code中的上下文使用示例：

📦 安装指南

目前该软件包尚未发布到npm，你需要克隆项目并在本地进行构建：

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

💻 使用示例

基础用法

当你编辑一个有语法错误的GDScript文件时：

# player.gd
extends CharacterBody2D

func _ready():
    velocity. = Vector2(100, 0)  # Missing identifier after '.'

MCP客户端将收到如下诊断信息：

{
  "diagnostics": {
    "/path/to/player.gd": [
      {
        "line": 5,
        "column": 14,
        "severity": "error",
        "message": "Expected identifier after '.'",
        "code": "parse-error"
      }
    ]
  }
}

高级用法

get_diagnostics

快速单文件诊断检查（<1秒）。 输入：

{
  "file_path": "/absolute/path/to/script.gd"
}

输出：

{
  "diagnostics": {
    "/path/to/file1.gd": [
      {
        "line": 42,
        "column": 10,
        "severity": "error",
        "message": "Expected identifier after '.'",
        "code": "GD0001"
      }
    ]
  }
}

scan_workspace_diagnostics

⚠️ 注意：这是一个开销较大的操作，会扫描工作区中的所有 .gd 文件（对于100多个文件，扫描时间为5 - 30秒）。请谨慎使用此操作进行工作区范围的错误检查，该操作需要设置 GODOT_WORKSPACE_PATH 环境变量。 输入：

{}

输出：

{
  "files_scanned": 150,
  "files_with_issues": 3,
  "scan_time_seconds": 12.45,
  "diagnostics": {
    "/path/to/file1.gd": [...],
    "/path/to/file2.gd": [...]
  }
}

📚 详细文档

配置

环境变量

在MCP客户端配置中设置以下环境变量，以自定义行为：

MCP客户端示例

Claude Code (~/.claude/config.json)：

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/minimal-godot-mcp/dist/index.js"],
      "env": {
        "GODOT_LSP_PORT": "6007",
        "GODOT_WORKSPACE_PATH": "/absolute/path/to/your/godot/project"
      }
    }
  }
}

比较

minimal-godot-mcp与其他Godot MCP服务器的区别：

使用minimal-godot-mcp的场景：当你在AI辅助的GDScript编辑过程中需要轻量级语法检查时。 使用其他替代方案的场景：当你需要场景管理、节点创建或完全项目控制时。

开发

架构

┌─────────────┐         ┌────────────────────┐         ┌────────────┐
│ MCP Client  │ ◄─MCP─► │ minimal-godot-mcp  │ ◄─LSP─► │   Godot    │
│             │         │   (TypeScript)     │         │   Editor   │
└─────────────┘         └────────────────────┘         └────────────┘

LSP通信流程：

1. 通过TCP连接到Godot LSP（尝试 localhost 的端口6007、6005、6008）
2. 发送LSP initialize 请求
3. 使用 textDocument/didOpen 同步文档
4. 接收 textDocument/publishDiagnostics 通知
5. 缓存并通过MCP get_diagnostics 工具提供服务

测试

npm test          # 单元测试
npm run lint      # ESLint + Prettier

手动测试步骤：

1. 使用测试项目启动Godot
2. 运行 npm run dev
3. 配置MCP客户端
4. 在 .gd 文件中引入语法错误
5. 验证诊断信息是否出现

贡献

欢迎贡献代码！有关设置，请参阅开发部分。在提交代码之前，请执行以下操作：

• 运行 npm run format 和 npm test
• 验证更改在实际Godot项目中是否有效
• 保持功能范围专注于诊断（不涉及项目操作）

故障排除

“端口6007连接被拒绝”

• Godot编辑器未运行
• 项目设置中LSP未启用
• 防火墙阻止了本地连接

“未返回诊断信息”

• 文件不属于Godot项目
• 文件未在编辑器中打开（LSP需要上下文）
• 语法实际上是有效的

“诊断信息过时”

• 文件更改时缓存未失效
• LSP未发送更新通知

启用LSP调试日志

在Godot中：项目 → 项目设置 → 网络 → 语言服务器 → 日志

相关项目

• Model Context Protocol - 协议规范
• Godot LSP Documentation - Godot的语言服务器设置
• awesome-mcp-servers - 精选的MCP服务器列表
• godot-vscode-plugin - 官方VSCode扩展（使用相同的LSP）

其他Godot MCP服务器：

• ee0pdt/Godot-MCP - 通过自定义插件实现完全项目控制
• Coding-Solo/godot-mcp - 基于CLI的GDScript操作

📄 许可证

本项目采用MIT许可证，请参阅LICENSE获取详细信息。