Gopls MCP

🚀 gopls-mcp

gopls-mcp 是一个模型上下文协议（MCP）服务器，它将 gopls（Go 语言服务器）与兼容 MCP 的主机（如 Claude Code、Claude Desktop 和 VS Code）集成在一起。本项目与 Claude Code 合作开发，旨在通过 MCP 协议提供无缝的 Go 语言服务器功能，从而在人工智能驱动的编码环境中实现强大的 Go 开发辅助。

🚀 快速开始

前提条件

• 拥有有效的 go.mod 文件的 Go 工作区
• 建议安装 Docker，或者安装 Go 1.24 及以上版本

分步设置

1. 克隆或下载一个 Go 项目以进行操作。
2. 启动 gopls-mcp 服务器：

   docker run -d -v $(pwd):/workspace -p 8080:8080 megagrindstone/gopls-mcp:latest
   

3. 与 Claude Code 集成：

   claude mcp add --transport http gopls-mcp http://localhost:8080
   

4. 测试集成 - 向 Claude Code 寻求 Go 代码方面的帮助！

✨ 主要特性

这个 MCP 服务器提供了14 种全面的 Go 开发工具，分为 6 个类别，并且完全支持多工作区：

🏢 工作区管理工具（1 种）

• 📋 列出工作区 - 发现并枚举所有已配置的 Go 工作区

🎯 核心导航工具（3 种）

• 🎯 转到定义 - 在 Go 工作区中导航到符号定义处
• 🔍 查找引用 - 定位函数、变量和类型的所有引用
• 📖 悬停信息 - 获取文档、类型信息和签名

🔍 诊断和分析工具（3 种）

• 🚨 获取诊断信息 - 获取 Go 文件的编译错误、警告和诊断信息
• 📄 文档符号 - 获取 Go 文件中定义的符号（函数、类型等）的大纲
• 🔎 工作区符号 - 在整个 Go 工作区/项目中搜索符号

💡 代码辅助工具（2 种）

• ✍️ 签名帮助 - 获取函数签名帮助和参数信息
• 🤖 代码补全 - 获取智能代码补全建议

🧭 高级导航工具（2 种）

• 🏷️ 类型定义 - 导航到符号的类型定义处
• 🔗 查找实现 - 查找接口或方法的所有实现

🛠️ 代码维护工具（3 种）

• ✨ 格式化文档 - 根据 gofmt 标准格式化 Go 源文件
• 📦 组织导入 - 组织和清理导入语句
• 💭 嵌入提示 - 获取隐式参数名称和类型信息的嵌入提示

所有工具都能与现有的 Go 工作区配合使用，同时支持多个工作区，并利用 gopls 提供准确、快速的结果。

📦 安装指南

与 Claude Code 集成（推荐）

使用 Streamable HTTP 传输方式，通过 Claude Code 使用 gopls-mcp 是最简单的方法：

1. 启动服务器并指定 Go 工作区：

   # 使用 Docker 启动单工作区（推荐）
   docker run -d -v /path/to/your/go/project:/workspace -p 8080:8080 megagrindstone/gopls-mcp:latest
   
   # 使用 Docker 启动多工作区
   docker run -d \
     -v /path/to/project1:/workspace1 \
     -v /path/to/project2:/workspace2 \
     -v /path/to/project3:/workspace3 \
     -p 8080:8080 \
     megagrindstone/gopls-mcp:latest -workspace /workspace1,/workspace2,/workspace3
   
   # 或者从源代码构建（单工作区）
   go build -o gopls-mcp
   ./gopls-mcp -workspace /path/to/your/go/project
   
   # 从源代码构建并启动多工作区
   ./gopls-mcp -workspace /path/to/project1,/path/to/project2,/path/to/project3
   

2. 添加到 Claude Code：

   claude mcp add --transport http gopls-mcp http://localhost:8080
   

3. 开始使用 - 在 Claude Code 对话中即可使用 Go 工具！

与 Claude Desktop 集成

对于 Claude Desktop，在 MCP 设置中添加以下内容：

单工作区

{
  "mcpServers": {
    "gopls-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/go/project:/workspace",
        "-p", "8080:8080",
        "megagrindstone/gopls-mcp:latest"
      ]
    }
  }
}

多工作区

{
  "mcpServers": {
    "gopls-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/project1:/workspace1",
        "-v", "/path/to/project2:/workspace2",
        "-v", "/path/to/project3:/workspace3",
        "-p", "8080:8080",
        "megagrindstone/gopls-mcp:latest",
        "-workspace", "/workspace1,/workspace2,/workspace3"
      ]
    }
  }
}

其他 MCP 主机

对于 VS Code 和其他 MCP 主机，使用 Streamable HTTP 传输方式：

{
  "servers": {
    "gopls-mcp": {
      "type": "http",
      "url": "http://localhost:8080"
    }
  }
}

💻 使用示例

集成完成后，你可以在对话中自然地使用这些工具。由于支持多工作区，你可以同时处理多个 Go 项目：

工作区管理

"有哪些可用的工作区？"
"列出所有已配置的 Go 项目"

核心导航工具

"在项目 1 中，`ProcessRequest` 函数在哪里定义？"
"显示所有工作区中 `UserService` 的所有使用位置"
"`http.Client` 结构体包含哪些内容？"

诊断和分析工具

"main.go 中是否有编译错误？"
"显示 client.go 中定义的所有函数和类型"
"在工作区中查找所有名为 'Handler' 的符号"

代码辅助工具

"`log.Printf` 函数接受哪些参数？"
"显示此位置的代码补全建议"

高级导航工具

"这个变量的类型定义是什么？"
"查找 Writer 接口的所有实现"

代码维护工具

"根据 gofmt 标准格式化这个 Go 文件"
"清理并组织此文件中的导入语句"
"显示此代码范围的类型提示"

MCP 服务器将根据你的请求自动使用适当的工具，并从你的 Go 工作区提供准确的信息。所有工具在处理多个项目时都支持特定于工作区的操作。

📚 详细文档

服务器选项

• -workspace（必需）：Go 工作区目录的路径

  • 单工作区：-workspace /path/to/project
  • 多工作区：-workspace /project1,/project2,/project3
  • 支持路径中包含空格：-workspace "/path with spaces/project1,/project2"

  ⚠️ 内存使用注意事项：每个工作区大约使用 300MB 的 RAM，因为它会运行一个独立的 gopls 进程。使用多个工作区时，请相应规划：

  • 1 个工作区：约 300MB RAM
  • 5 个工作区：约 1.5GB RAM
  • 10 个工作区：约 3GB RAM

• -transport（可选）：传输类型，接受 'http' 或 'stdio'（默认为 'http'）

• 端口：固定为 8080（仅适用于 Streamable HTTP 传输）

传输选项

Streamable HTTP 传输（默认）

# 使用 Streamable HTTP 传输的单工作区（默认）
./gopls-mcp -workspace /path/to/go/project
./gopls-mcp -workspace /path/to/go/project -transport http

# 使用 Streamable HTTP 传输的多工作区
./gopls-mcp -workspace /project1,/project2,/project3
./gopls-mcp -workspace /project1,/project2 -transport http

# 使用 Docker 的单工作区（Streamable HTTP 传输）
docker run -v /path/to/go/project:/workspace -p 8080:8080 megagrindstone/gopls-mcp:latest

# 使用 Docker 的多工作区（Streamable HTTP 传输）
docker run \
  -v /project1:/workspace1 \
  -v /project2:/workspace2 \
  -v /project3:/workspace3 \
  -p 8080:8080 \
  megagrindstone/gopls-mcp:latest -workspace /workspace1,/workspace2,/workspace3

Stdio 传输

# 使用 stdio 传输的单工作区
./gopls-mcp -workspace /path/to/go/project -transport stdio

# 使用 stdio 传输的多工作区
./gopls-mcp -workspace /project1,/project2,/project3 -transport stdio

# 使用 Docker 的单工作区（stdio 传输）
docker run -i -v /path/to/go/project:/workspace megagrindstone/gopls-mcp:latest -transport stdio

# 使用 Docker 的多工作区（stdio 传输）
docker run -i \
  -v /project1:/workspace1 \
  -v /project2:/workspace2 \
  -v /project3:/workspace3 \
  megagrindstone/gopls-mcp:latest -workspace /workspace1,/workspace2,/workspace3 -transport stdio

对于使用 stdio 传输的 Claude Desktop：

{
  "mcpServers": {
    "gopls-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/go/project:/workspace",
        "megagrindstone/gopls-mcp:latest",
        "-transport", "stdio"
      ]
    }
  }
}

日志配置

服务器支持通过环境变量进行结构化日志记录，可配置日志级别和格式：

环境变量

• LOG_LEVEL：设置日志级别（DEBUG、INFO、WARN、ERROR） - 默认为 INFO
• LOG_FORMAT：设置日志输出格式（text、json） - 默认为 text

使用示例

# 本地运行并自定义日志记录
LOG_LEVEL=DEBUG ./gopls-mcp -workspace /path/to/go/project
LOG_FORMAT=json LOG_LEVEL=WARN ./gopls-mcp -workspace /path/to/go/project

# 使用 Docker 并配置日志记录
docker run -e LOG_LEVEL=DEBUG -v /path/to/go/project:/workspace -p 8080:8080 megagrindstone/gopls-mcp:latest
docker run -e LOG_FORMAT=json -e LOG_LEVEL=INFO -v /path/to/go/project:/workspace -p 8080:8080 megagrindstone/gopls-mcp:latest

工作区要求

你的 Go 工作区必须包含：

• 有效的 go.mod 文件
• 正确的 Go 模块结构
• 可访问的 Go 源文件

服务器将自动使用你的工作区初始化 gopls，并在整个会话期间维护语言服务器连接。

Docker 部署

使用 Docker Hub 镜像

我在 Docker Hub 上维护了预构建的 Docker 镜像，支持多平台：

# 最新稳定版本
docker pull megagrindstone/gopls-mcp:latest

# 特定版本
docker pull megagrindstone/gopls-mcp:v0.3.0

# 运行单 Go 项目
docker run -v /path/to/go/project:/workspace -p 8080:8080 megagrindstone/gopls-mcp:latest

# 运行多 Go 项目
docker run \
  -v /path/to/project1:/workspace1 \
  -v /path/to/project2:/workspace2 \
  -v /path/to/project3:/workspace3 \
  -p 8080:8080 \
  megagrindstone/gopls-mcp:latest -workspace /workspace1,/workspace2,/workspace3

可用标签

• latest - 最新稳定版本
• v* - 语义化版本标签（例如，v0.3.0）
• main - 最新开发版本

多平台支持

Docker 镜像支持：

• linux/amd64 - Intel/AMD 64 位
• linux/arm64 - ARM 64 位（Apple Silicon、ARM 服务器）

开发设置

前提条件

• Go 1.24 及以上版本
• Docker（可选）
• golangci-lint（可选，用于代码检查）

从源代码构建

# 克隆仓库
git clone https://github.com/MegaGrindStone/gopls-mcp.git
cd gopls-mcp

# 构建二进制文件
go build -o gopls-mcp

# 运行单 Go 工作区
./gopls-mcp -workspace /path/to/your/go/project

# 运行多 Go 工作区
./gopls-mcp -workspace /path/to/project1,/path/to/project2,/path/to/project3

测试

# 运行测试并输出详细信息
go test ./... -v -count=1 -p 1

# 运行代码检查器
golangci-lint run ./...

# 格式化代码
go fmt ./...

Docker 开发

# 构建 Docker 镜像
docker build -t gopls-mcp .

# 本地测试单工作区
docker run -v /path/to/test/project:/workspace -p 8080:8080 gopls-mcp

# 本地测试多工作区
docker run \
  -v /path/to/test/project1:/workspace1 \
  -v /path/to/test/project2:/workspace2 \
  -p 8080:8080 \
  gopls-mcp -workspace /workspace1,/workspace2

🔧 技术细节

API 参考

MCP 工具

所有工具都需要一个 workspace 参数来指定要操作的工作区。在工作区内使用相对路径。

🏢 工作区管理工具

list_workspaces

列出服务器中配置的所有可用 Go 工作区。 参数：无 示例：

{
  "name": "list_workspaces",
  "arguments": {}
}

🎯 核心导航工具

go_to_definition

在 Go 工作区中导航到符号定义处。 参数：

• workspace（字符串）：用于此请求的工作区路径
• path（字符串）：Go 文件的相对路径（例如，main.go、pkg/client.go）
• line（数字）：行号（从 1 开始）
• character（数字）：字符位置（从 0 开始） 示例：

{
  "name": "go_to_definition",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "main.go",
    "line": 10,
    "character": 5
  }
}

find_references

在 Go 工作区中查找符号的所有引用。 参数：

• workspace（字符串）：用于此请求的工作区路径
• path（字符串）：Go 文件的相对路径
• line（数字）：行号（从 1 开始）
• character（数字）：字符位置（从 0 开始）
• includeDeclaration（布尔值）：结果中是否包含声明 示例：

{
  "name": "find_references",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "pkg/client.go",
    "line": 10,
    "character": 5,
    "includeDeclaration": true
  }
}

get_hover_info

获取符号的文档和类型信息。 参数：

• workspace（字符串）：用于此请求的工作区路径
• path（字符串）：Go 文件的相对路径
• line（数字）：行号（从 1 开始）
• character（数字）：字符位置（从 0 开始） 示例：

{
  "name": "get_hover_info",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "mcp.go",
    "line": 10,
    "character": 5
  }
}

🔍 诊断和分析工具

get_diagnostics

获取 Go 文件的编译错误、警告和诊断信息。 参数：

• workspace（字符串）：用于此请求的工作区路径
• path（字符串）：Go 文件的相对路径 示例：

{
  "name": "get_diagnostics",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "main.go"
  }
}

get_document_symbols

获取 Go 文件中定义的符号（函数、类型等）的大纲。 参数：

• workspace（字符串）：用于此请求的工作区路径
• path（字符串）：Go 文件的相对路径 示例：

{
  "name": "get_document_symbols",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "client.go"
  }
}

get_workspace_symbols

在整个 Go 工作区/项目中搜索符号。 参数：

• workspace（字符串）：用于此请求的工作区路径
• query（字符串）：要搜索的符号名称 示例：

{
  "name": "get_workspace_symbols",
  "arguments": {
    "workspace": "/path/to/workspace",
    "query": "Client"
  }
}

💡 代码辅助工具

get_signature_help

在指定位置获取函数签名帮助（参数信息）。 参数：

• workspace（字符串）：用于此请求的工作区路径
• path（字符串）：Go 文件的相对路径
• line（数字）：行号（从 1 开始）
• character（数字）：字符位置（从 0 开始） 示例：

{
  "name": "get_signature_help",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "main.go",
    "line": 15,
    "character": 20
  }
}

get_completions

在指定位置获取代码补全建议。 参数：

• workspace（字符串）：用于此请求的工作区路径
• path（字符串）：Go 文件的相对路径
• line（数字）：行号（从 1 开始）
• character（数字）：字符位置（从 0 开始） 示例：

{
  "name": "get_completions",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "main.go",
    "line": 8,
    "character": 5
  }
}

🧭 高级导航工具

get_type_definition

在指定位置导航到符号的类型定义处。 参数：

• workspace（字符串）：用于此请求的工作区路径
• path（字符串）：Go 文件的相对路径
• line（数字）：行号（从 1 开始）
• character（数字）：字符位置（从 0 开始） 示例：

{
  "name": "get_type_definition",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "client.go",
    "line": 25,
    "character": 10
  }
}

find_implementations

在指定位置查找接口或方法的所有实现。 参数：

• workspace（字符串）：用于此请求的工作区路径
• path（字符串）：Go 文件的相对路径
• line（数字）：行号（从 1 开始）
• character（数字）：字符位置（从 0 开始） 示例：

{
  "name": "find_implementations",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "interfaces.go",
    "line": 12,
    "character": 8
  }
}

🛠️ 代码维护工具

format_document

根据 gofmt 标准格式化 Go 源文件。 参数：

• workspace（字符串）：用于此请求的工作区路径
• path（字符串）：Go 文件的相对路径 示例：

{
  "name": "format_document",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "main.go"
  }
}

organize_imports

组织和清理 Go 文件中的导入语句。 参数：

• workspace（字符串）：用于此请求的工作区路径
• path（字符串）：Go 文件的相对路径 示例：

{
  "name": "organize_imports",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "client.go"
  }
}

get_inlay_hints

获取 Go 文件中某个范围的嵌入提示（隐式参数名称、类型信息）。 参数：

• workspace（字符串）：用于此请求的工作区路径
• path（字符串）：Go 文件的相对路径
• startLine（数字）：起始行号（从 1 开始）
• startChar（数字）：起始字符位置（从 0 开始）
• endLine（数字）：结束行号（从 1 开始）
• endChar（数字）：结束字符位置（从 0 开始） 示例：

{
  "name": "get_inlay_hints",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "main.go",
    "startLine": 10,
    "startChar": 0,
    "endLine": 20,
    "endChar": 50
  }
}

问题排查

常见问题

“需要 -workspace 标志”

• 确保在运行服务器时提供 -workspace 标志
• 工作区路径必须包含有效的 Go 模块

“无法启动 gopls”

• 检查 gopls 是否在你的 PATH 中（在 Docker 中会自动处理）
• 确保你的 Go 工作区有有效的 go.mod 文件
• 验证工作区路径是否可访问

“连接被拒绝”

• 确保服务器在端口 8080 上运行
• 检查是否有其他服务正在使用该端口
• 验证 MCP 服务器是否可在 http://localhost:8080 访问

调试模式

要调试问题，请使用详细日志记录运行服务器：

# 本地运行并开启调试日志
LOG_LEVEL=DEBUG ./gopls-mcp -workspace /path/to/project

# 使用 Docker 并开启调试日志（Streamable HTTP）
docker run -e LOG_LEVEL=DEBUG -v /path/to/project:/workspace -p 8080:8080 megagrindstone/gopls-mcp:latest

# 查看 Docker 容器日志
docker logs <container-id>

# 使用 JSON 格式日志以便于解析
docker run -e LOG_FORMAT=json -e LOG_LEVEL=DEBUG -v /path/to/project:/workspace -p 8080:8080 megagrindstone/gopls-mcp:latest

贡献代码

我欢迎大家为改进 gopls-mcp 做出贡献！本项目是与 Claude Code 合作开发的，我很高兴看到社区能够进一步完善它。

开发流程

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 运行测试套件：go test ./... -v -count=1 -p 1
6. 运行代码检查器：golangci-lint run ./...
7. 提交拉取请求

代码风格

• 遵循标准的 Go 约定
• 使用 go fmt 进行格式化
• 遵循代码库中的现有模式
• 为新功能添加测试

报告问题

请在 GitHub 问题跟踪器 上报告问题，并提供以下信息：

• 你的操作系统和 Go 版本
• 重现问题的步骤
• 预期行为与实际行为
• 相关日志或错误消息

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

致谢

• Claude Code - 本项目与 Claude Code（Anthropic 公司的人工智能编码助手）合作开发
• gopls 团队 - 开发了出色的 Go 语言服务器
• 模型上下文协议 - 提供了实现此集成的框架
• Go 社区 - 构建了使这一切成为可能的工具和生态系统

---

作者：Gerard Adam
合作方：与 Claude Code 合作开发
仓库地址：https://github.com/MegaGrindStone/gopls-mcp
Docker Hub：https://hub.docker.com/r/megagrindstone/gopls-mcp