JinDaGe - minimal-godot-mcp MCP Details

article

README

🚀 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中的上下文使用示例： context-use

📦 安装指南

目前该软件包尚未发布到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客户端配置中设置以下环境变量，以自定义行为： | 属性 | 详情 | |------|------| | GODOT_LSP_PORT | 覆盖默认端口选择。默认按顺序尝试端口6007、6005、6008。示例："GODOT_LSP_PORT": "6005" | | GODOT_WORKSPACE_PATH | 设置Godot项目路径，用于LSP初始化。默认使用Godot通知中的工作区。示例："GODOT_WORKSPACE_PATH": "/absolute/path/to/your/godot/project" |

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 | ee0pdt/Godot-MCP | Coding-Solo/godot-mcp | |------------------------|-------------------|------------------|-----------------------| | 是否需要自定义插件 | ❌ | ✅ | ❌ | | 是否支持项目操作 | ❌ | ✅ | ✅ | | LSP集成方式 | ✅ 原生 | ❌ 自定义 | ❌ GDScript操作 | | 功能范围 | 仅诊断 | 完全控制 | CLI + 脚本 |

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

开发

架构

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

LSP通信流程：

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

测试

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

手动测试步骤：

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

贡献

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

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

故障排除

“端口6007连接被拒绝”

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

“未返回诊断信息”

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

“诊断信息过时”

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

启用LSP调试日志

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

📄 许可证

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

minimal-godot-mcp