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