Skip to content
Back to search

mcp-gopls

Model Context Protocol (MCP) server for Go using gopls – LSP-powered analysis, tests, coverage, and tooling.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hloiseau--mcp-gopls/badge.svg)](/listings/hloiseau--mcp-gopls)

HTML

<a href="/listings/hloiseau--mcp-gopls"><img src="/api/listings/hloiseau--mcp-gopls/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

go install github.com/hloiseau/mcp-gopls/v2/cmd/mcp-gopls@latest

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 427 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # mcp-gopls – MCP server for Go (gopls)
  2. <!-- markdownlint-disable MD022 MD012 MD029 MD060 -->
  3. [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
  4. ![Go version](https://img.shields.io/badge/Go-1.25+-informational)
  5. [![CI](https://github.com/hloiseau/mcp-gopls/actions/workflows/ci.yml/badge.svg)](https://github.com/hloiseau/mcp-gopls/actions)
  6. [![Docker Image](https://img.shields.io/badge/ghcr.io-hloiseau/mcp--gopls-blue)](https://ghcr.io/hloiseau/mcp-gopls)
  7. A Model Context Protocol (MCP) server that lets AI assistants use Go’s LSP (`gopls`) for navigation, diagnostics, testing, coverage, and more.
  8. > **TL;DR:** If you use Claude / Cursor / Copilot with Go, `mcp-gopls` gives the AI full LSP powers:
  9. > go-to-definition, references, hover, completion, `go test`, coverage, `go mod tidy`, `govulncheck`, etc.
  10. ![Demo Animation](docs/Animation.gif)
  11. ## Overview
  12. This MCP server helps AI assistants to:
  13. - Use LSP to analyze Go workspaces
  14. - Navigate to definitions, references, and workspace symbols
  15. - Format, rename, and inspect code actions without leaving MCP
  16. - Run Go tests, coverage, `go mod tidy`, `govulncheck`, and module graph commands with structured results
  17. - Read workspace resources (overview + go.mod) and consume curated prompts
  18. > **Status:** Actively developed – used in real projects.
  19. > Tested with Go 1.25.x and `gopls@latest`.
  20. ## Architecture
  21. This project uses the [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go) library to implement the Model Context Protocol. The MCP integration enables seamless communication between AI assistants and Go tools.
  22. The server communicates with [gopls](https://github.com/golang/tools/tree/master/gopls), the official language server for Go, via the Language Server Protocol (LSP).
  23. ## Features
  24. - **Configurable runtime**: `--workspace`, `--gopls-path`, `--log-level`, `--rpc-timeout`, and `--shutdown-timeout` flags + env vars (`MCP_GOPLS_*`)
  25. - **Structured logging**: Text/JSON logging with slog and optional file output
  26. - **Extended LSP surface**: navigation, diagnostics, formatting, rename, code actions, hover, completion, workspace symbols
  27. - **Test & tooling helpers**: coverage analysis, `go test`, `go mod tidy`, `govulncheck`, `go mod graph`
  28. - **MCP extras**: resources (`resource://workspace/overview`, `resource://workspace/go.mod`) and prompts (`summarize_diagnostics`, `refactor_plan`)
  29. - **Progress streaming**: long-running commands emit `notifications/progress` events so clients can surface status updates
  30. ### Feature comparison: `mcp-gopls` vs built-in `gopls` MCP
  31. As of `gopls` v0.20.0, the built-in MCP server exposes these tools:
  32. `go_context`, `go_diagnostics`, `go_file_context`, `go_file_diagnostics`,
  33. `go_file_metadata`, `go_package_api`, `go_references`, `go_rename_symbol`,
  34. `go_search`, `go_symbol_references`, `go_workspace`, `go_vulncheck`.
  35. | Feature / capability | `mcp-gopls` (this project) | Built-in `gopls` MCP |
  36. |----------------------|----------------------------|----------------------|
  37. | Go-to-definition | Yes (`go_to_definition` tool) | No dedicated MCP tool (not in tool list) |
  38. | Find references | Yes (`find_references`) | Yes (`go_references`, `go_symbol_references`) |
  39. | Diagnostics (file / workspace) | Yes (`check_diagnostics`) | Yes (`go_diagnostics`, `go_file_diagnostics`) |
  40. | Hover information | Yes (`get_hover_info`) | No dedicated MCP tool (not in tool list) |
  41. | Completion | Yes (`get_completion`) | No dedicated MCP tool (not in tool list) |
  42. | Formatting | Yes (`format_document`) | No dedicated MCP tool (not in tool list) |
  43. | Rename symbol | Yes (`rename_symbol`) | Yes (`go_rename_symbol`) |
  44. | Code actions | Yes (`list_code_actions`) | No dedicated MCP tool (not in tool list) |
  45. | Workspace symbol search | Yes (`search_workspace_symbols`) | Yes (`go_search`) |
  46. | Package / workspace API/context tools | No dedicated MCP tool | Yes (`go_package_api`, `go_file_context`, `go_file_metadata`, `go_workspace`, `go_context`) |
  47. | Run `go test` | Yes (`run_go_test`) | No MCP tool for running tests |
  48. | Coverage analysis | Yes (`analyze_coverage`) | No MCP tool for coverage |
  49. | `go mod tidy` | Yes (`run_go_mod_tidy`) | No MCP tool for `go mod tidy` |
  50. | `govulncheck` | Yes (`run_govulncheck`) | Yes (`go_vulncheck`) |
  51. | Module graph (`go mod graph`) | Yes (`module_graph`) | No MCP tool for module graph |
  52. | Extra MCP resources | Yes (`resource://workspace/overview`, `resource://workspace/go.mod`) | Not documented as MCP resources |
  53. | Custom MCP prompts | Yes (`summarize_diagnostics`, `refactor_plan`) | Not exposed as MCP prompts (only model instructions) |
  54. | Model instructions shipped with server | No special mechanism (documented in README/docs) | Yes: `gopls mcp -instructions` prints usage workflows |
  55. If you want full LSP-like editing + tooling from MCP (definition, hover, completion, format, rename, code actions, go test, coverage, go mod tidy, module graph), mcp-gopls is strictly richer.
  56. If you mostly want read-only/introspective tools (diagnostics, symbol search, references, package API, workspace/file context, vulncheck) with no extra binary, the built-in gopls MCP is enough.
  57. > **Note:** The built-in `gopls` MCP server is still marked experimental and its tool set may change over time. This comparison is accurate as of `gopls` v0.20.x.
  58. ## Project Structure
  59. ```bash
  60. .
  61. ├── cmd
  62. │ └── mcp-gopls # Application entry point
  63. ├── pkg
  64. │ ├── lsp # LSP client to communicate with gopls
  65. │ │ ├── client # LSP client implementation
  66. │ │ └── protocol # LSP protocol types and features
  67. │ ├── server # MCP server
  68. │ └── tools # MCP tools exposing LSP features
  69. ```
  70. ## Installation
  71. ```bash
  72. go install github.com/hloiseau/mcp-gopls/v2/cmd/mcp-gopls@latest
  73. ```
  74. ## Quick Start
  75. 1. **Install** the server:
  76. ```bash
  77. go install github.com/hloiseau/mcp-gopls/v2/cmd/mcp-gopls@latest
  78. ```
  79. 2. **Verify** it's on your `$PATH`:
  80. ```bash
  81. mcp-gopls --help
  82. ```
  83. 3. **Configure** your AI client (see examples below for Cursor, Claude Desktop, or GitHub Copilot).
  84. ---
  85. ## Docker / MCP Gateway
  86. If you prefer to run `mcp-gopls` in a container (for Docker MCP Gateway or other containerized setups), use the official image.
  87. ### Docker run
  88. ```bash
  89. docker run --rm -i \
  90. -v /absolute/path/to/your/go/project:/workspace \
  91. ghcr.io/hloiseau/mcp-gopls:latest \
  92. --workspace /workspace
  93. ```
  94. ### docker-mcp.yaml
  95. Copy `docs/docker-mcp.yaml`, update the bind mount path, then run from that directory:
  96. ```bash
  97. docker mcp gateway run
  98. ```
  99. ### Tools catalog metadata
  100. If your MCP catalog tooling requires a `toolsUrl`, use `docs/tools.json` as a static tool list.
  101. ## Detailed Client Setup
  102. > **Note:** All clients point to the same command:
  103. > `mcp-gopls --workspace /absolute/path/to/your/go/project`
  104. > The configuration format differs slightly per client, but the binary and arguments remain identical.
  105. ### 1. Connect from Cursor
  106. 1. Open **Settings → MCP Servers → Edit JSON**.
  107. 2. Add or update the `mcp-gopls` entry:
  108. ```json
  109. {
  110. "mcpServers": {
  111. "mcp-gopls": {
  112. "command": "mcp-gopls",
  113. "args": ["--workspace", "/absolute/path/to/your/go/project"],
  114. "env": {
  115. "MCP_GOPLS_LOG_LEVEL": "info"
  116. }
  117. }
  118. }
  119. }
  120. ```
  121. 3. Run **Developer: Reload Window** so Cursor reconnects.
  122. 4. Open the **Tools** drawer in Cursor Chat and enable `mcp-gopls`.
  123. ### 2. Invoke the tools
  124. | Tool / Prompt | Example request inside Cursor Chat |
  125. |---------------|------------------------------------|
  126. | `go_to_definition` | “Use `go_to_definition` on `pkg/server/server.go:42`.” |
  127. | `find_references` | “Ask the tool for references to `ServeStdio`.” |
  128. | `check_diagnostics` | “Request diagnostics for `cmd/mcp-gopls/main.go`.” |
  129. | `get_hover_info` | “Call `get_hover_info` on `pkg/tools/workspace.go:88`.” |
  130. | `get_completion` | “Trigger completions at `pkg/server/server.go:55`.” |
  131. | `format_document` | “Run the formatter over `pkg/tools/refactor.go`.” |
  132. | `rename_symbol` | “Rename `clientFactory` to `newClientFactory` via the tool.” |
  133. | `list_code_actions` | “List code actions for `pkg/server/server.go:80-90`.” |
  134. | `search_workspace_symbols` | “Search workspace symbols for `NewWorkspaceConfig`.” |
  135. | `analyze_coverage` | “Run `analyze_coverage` for `./pkg/...` with per-function stats.” |
  136. | `run_go_test` | “Execute `run_go_test` on `./cmd/...`.” |
  137. | `run_go_mod_tidy` | “Invoke `run_go_mod_tidy` to sync go.mod.” |
  138. | `run_govulncheck` | “Run `run_govulncheck` and stream findings.” |
  139. | `module_graph` | “Call `module_graph` to inspect dependencies.” |
  140. | `summarize_diagnostics` | “Use the `summarize_diagnostics` prompt on the latest diagnostics.” |
  141. | `refactor_plan` | “Feed `refactor_plan` the diagnostics JSON to plan fixes.” |
  142. ## Client Setup Examples
  143. ### Claude Desktop (macOS, Windows, Linux)
  144. 1. Install `mcp-gopls` and make sure it is on your `$PATH`.
  145. 2. Create or edit `claude_desktop_config.json`.
  146. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  147. - Linux: `~/.config/Claude/claude_desktop_config.json`
  148. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  149. 3. Add the server entry:
  150. ```json
  151. {
  152. "mcpServers": {
  153. "mcp-gopls": {
  154. "command": "mcp-gopls",
  155. "args": ["--workspace", "/absolute/path/to/your/go/project"],
  156. "env": {
  157. "MCP_GOPLS_LOG_LEVEL": "info"
  158. }
  159. }
  160. }
  161. }
  162. ```
  163. Restart Claude Desktop, open a chat, and ask it to connect to the `mcp-gopls` tool (Claude will show a “Tools” tab once the server is detected). Typical prompts include “list diagnostics for `cmd/api/server.go`” or “rename `userService` to `accountService`.”
  164. ### Cursor IDE
  165. In Cursor open **Settings → MCP Servers → Edit JSON** (this writes to `~/.cursor/config.json` or the project-local override). Add:
  166. ```json
  167. {
  168. "mcpServers": {
  169. "mcp-gopls": {
  170. "command": "mcp-gopls",
  171. "args": ["--workspace", "/absolute/path/to/your/go/project"]
  172. }
  173. }
  174. }
  175. ```
  176. Reload Cursor (or run the `Developer: Reload Window` command) and the server will appear inside the “Tools” drawer. You can now ask Cursor Chat things like “run `go test ./pkg/server` with coverage” or “show hover info for `pkg/tools/tests.go:42`.”
  177. ### GitHub Copilot (Agent Mode)
  178. GitHub Copilot’s Agent Mode can talk to local MCP servers across VS Code, JetBrains IDEs, Eclipse, and Xcode ([docs](https://docs.github.com/en/copilot/customizing-copilot/extending-copilot-chat-with-mcp)). To wire `mcp-gopls` in VS Code:
  179. 1. Update GitHub Copilot (requires VS Code 1.99+), opt into **Agent Mode**.
  180. 2. Create `.vscode/mcp.json` in your workspace (or edit the global file shown in the Copilot “Edit config” dialog).
  181. 3. Add:
  182. ```json
  183. {
  184. "servers": {
  185. "mcp-gopls": {
  186. "type": "stdio",
  187. "command": "mcp-gopls",
  188. "args": ["--workspace", "/absolute/path/to/your/go/project"],
  189. "env": {
  190. "MCP_GOPLS_LOG_LEVEL": "warn"
  191. }
  192. }
  193. }
  194. }
  195. ```
  196. 4. Reload Agent Mode (toggle off/on) so Copilot discovers the new tool; the chat “Tools” picker will now expose every MCP action (`run_go_test`, `run_govulncheck`, etc.). JetBrains and other IDEs share the same JSON schema via their Copilot settings panel.
  197. ### MCP Inspector / CLI testing
  198. For quick smoke tests or demos you can use [mark3labs/mcp-inspector](https://github.com/mark3labs/mcp-inspector):
  199. ```bash
  200. npx -y @mark3labs/mcp-inspector \
  201. --command mcp-gopls \
  202. --args "--workspace" "/absolute/path/to/your/go/project"
  203. ```
  204. The inspector lets you call each tool/resource/prompt manually, which is handy for debugging server configuration before wiring it into an AI assistant.
  205. ## MCP Tools
  206. | Tool | Description |
  207. |------|-------------|
  208. | `go_to_definition` | Navigate to the definition of a symbol |
  209. | `find_references` | List all references for a symbol |
  210. | `check_diagnostics` | Fetch cached diagnostics for a file |
  211. | `get_hover_info` | Return hover markdown for a symbol |
  212. | `get_completion` | Return completion labels at a position |
  213. | `format_document` | Return formatting edits for an entire document |
  214. | `rename_symbol` | Return workspace edits for a rename |
  215. | `list_code_actions` | List available code actions for a range |
  216. | `search_workspace_symbols` | Search workspace-wide symbols |
  217. | `analyze_coverage` | Run `go test` with coverage + optional per-function report |
  218. | `run_go_test` | Execute `go test` for a package/pattern |
  219. | `run_go_mod_tidy` | Execute `go mod tidy` |
  220. | `run_govulncheck` | Execute `govulncheck ./...` |
  221. | `module_graph` | Return `go mod graph` output |
  222. ## Progress Notifications
  223. Long-running tools emit structured `notifications/progress` events so IDEs can show rich status indicators:
  224. - **Streaming progress** (`run_go_test`, `analyze_coverage`, `run_govulncheck`, `run_go_mod_tidy`) forwards incremental log lines and percentage updates. Cursor displays these as a live log.
  225. - **Start/complete events only** (`go_to_definition`, `find_references`, `rename_symbol`, etc.) fire a quick “started” event so the UI can show a spinner, followed by a completion payload with the final result.
  226. - Each progress token is now namespaced (e.g., `run_go_test/<rand>`) to avoid “unknown token” errors when multiple tools run concurrently.
  227. When integrating new tools, opt into streaming mode only if the underlying LSP/golang command produces meaningful interim output; otherwise stick to the lightweight start/complete flow to minimize noise.
  228. ## Prompt Instructions
  229. Both prompts are accessible from any MCP-aware client via the “Prompts” catalog.
  230. ### `summarize_diagnostics`
  231. - **When to use:** After `check_diagnostics` or `run_go_test` to turn raw diagnostics into actionable steps.
  232. - **Arguments:** None. The server automatically reads the last diagnostics payload cached by the tools layer.
  233. - **Typical workflow:** `check_diagnostics` → copy the returned array into the prompt input field (Cursor’s UI pastes it automatically when you select “Use last result”).
  234. ### `refactor_plan`
  235. - **When to use:** You already have a diagnostics JSON array and want a concise change checklist.
  236. - **Arguments:** Requires a `diagnostics` object containing the raw Go diagnostics (the same payload returned by `check_diagnostics`).
  237. - **Example invocation payload:**
  238. ```json
  239. {
  240. "diagnostics": [
  241. {
  242. "uri": "file:///path/to/pkg/tools/workspace.go",
  243. "range": {"start": {"line": 12, "character": 5}, "end": {"line": 12, "character": 25}},
  244. "severity": 1,
  245. "message": "unused variable testHelper"
  246. }
  247. ]
  248. }
  249. ```
  250. The prompt responds with a numbered set of refactor steps plus suggested validation commands (`go test`, `analyze_coverage`, etc.).
  251. ## Configuration
  252. The server supports various configuration options via command-line flags and environment variables:
  253. ### Command-Line Flags
  254. | Flag | Default | Description |
  255. |-----------------------|---------|------------------------------------------------|
  256. | `--workspace` | `.` | Absolute path to your Go project root |
  257. | `--gopls-path` | `gopls` | Path to the gopls binary |
  258. | `--log-level` | `info` | Log level (`debug`, `info`, `warn`, `error`) |
  259. | `--rpc-timeout` | `30s` | RPC timeout for LSP calls |
  260. | `--shutdown-timeout` | `5s` | Timeout for graceful shutdown |
  261. ### Environment Variables
  262. All flags can be set via environment variables with the `MCP_GOPLS_` prefix:
  263. | Environment Variable | Equivalent Flag | Description |
  264. |---------------------------|-----------------------|------------------------------------------------|
  265. | `MCP_GOPLS_WORKSPACE` | `--workspace` | Absolute path to your Go project root |
  266. | `MCP_GOPLS_GOPLS_PATH` | `--gopls-path` | Path to the gopls binary |
  267. | `MCP_GOPLS_LOG_LEVEL` | `--log-level` | Log level (`debug`, `info`, `warn`, `error`) |
  268. | `MCP_GOPLS_RPC_TIMEOUT` | `--rpc-timeout` | RPC timeout for LSP calls (e.g., `30s`, `1m`) |
  269. | `MCP_GOPLS_SHUTDOWN_TIMEOUT` | `--shutdown-timeout` | Timeout for graceful shutdown |
  270. Command-line flags take precedence over environment variables.
  271. ## Troubleshooting
  272. - **“column is beyond end of line”** – gopls could not map the provided position. Confirm the file is saved and the position uses zero-based lines/columns; run `go fmt` to ensure tabs vs. spaces align with gopls expectations.
  273. - **“no hover information available”** – the symbol might belong to a generated file or a module outside the configured workspace. Ensure the `--workspace` flag points to the module root and that `go list ./...` succeeds.
  274. - **“workspace not initialized”** – the server did not finish its initial sync. Wait for the `workspace initialized` log line or restart `mcp-gopls` after deleting stale `.gopls` caches.
  275. - **`run_govulncheck` missing binary** – the tool now falls back to `go run golang.org/x/vuln/cmd/govulncheck@latest`, but the machine still needs outbound network access. Install the binary manually if the fallback is blocked.
  276. ## Usage Example
  277. Using the server with AI assistants that support MCP:
  278. ```Markdown
  279. # Ask the AI to get information about the code
  280. Can you find the definition of the `ServeStdio` function in this project?
  281. # Ask for diagnostics
  282. Are there any errors in my main.go file?
  283. # Ask for information about a symbol
  284. What does the Context.WithTimeout function do in Go?
  285. ```
  286. ## Development
  287. ```bash
  288. git clone https://github.com/hloiseau/mcp-gopls.git
  289. cd mcp-gopls
  290. go mod tidy
  291. go test ./...
  292. go build ./cmd/mcp-gopls
  293. ```
  294. Table-driven tests live under `pkg/tools` and CI runs via `.github/workflows/ci.yml`.
  295. ### Documentation
  296. - `docs/usage.md` – quickstart and tool catalog walkthrough
  297. - Workspace resources expose `resource://workspace/overview` and `resource://workspace/go.mod`
  298. - Prompts (`summarize_diagnostics`, `refactor_plan`) help assistants produce consistent outputs
  299. ## Contributing
  300. PRs and issues are welcome!
  301. - Check [open issues](https://github.com/hloiseau/mcp-gopls/issues) or file a new one if you hit a bug or want a feature.
  302. - Run `go test ./...` before opening a PR.
  303. - For bigger changes (new tools, protocol changes), please open a design issue first so we can discuss the approach.
  304. All contributions should maintain test coverage and adhere to Go best practices. See the [Development](#development) section for setup instructions.
  305. ## Prerequisites
  306. - Go 1.25+ (tested with `go1.25.4`)
  307. - `gopls` installed (`go install golang.org/x/tools/gopls@latest`)
  308. - Optional: `govulncheck` (`go install golang.org/x/vuln/cmd/govulncheck@latest`)
  309. - The server forces `GOTOOLCHAIN=local` for its nested `gopls` process. If you need a different toolchain, set `GOTOOLCHAIN` in the environment before launching `mcp-gopls`.
  310. ## Integration with Ollama
  311. This MCP server can be used with any tool that supports the MCP protocol. For Ollama integration:
  312. 1. Make sure Ollama is running
  313. 2. The MCP server runs independently and communicates through stdin/stdout
  314. 3. Configure your client to use the MCP server as a tool provider
  315. ## License
  316. Apache License 2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.