A Model Context Protocol (MCP) server that lets AI assistants use Go’s LSP (gopls) for navigation, diagnostics, testing, coverage, and more. This MCP server helps AI assistants to: - Use LSP to analyze Go workspaces - Navigate to definitions, references, and workspace symbols - Format, rename, and inspect code actions without leaving MCP - Run Go tests, coverage, go mod tidy, govulncheck, and modu
Add this skill
npx mdskills install hloiseaufcms/mcp-goplsComprehensive MCP bridge to gopls LSP with extensive tooling, solid docs, but network permission unclear
1# mcp-gopls – MCP server for Go (gopls)2<!-- markdownlint-disable MD022 MD012 MD029 MD060 -->3[](LICENSE)45[](https://github.com/hloiseau/mcp-gopls/actions)6[](https://ghcr.io/hloiseau/mcp-gopls)78A Model Context Protocol (MCP) server that lets AI assistants use Go’s LSP (`gopls`) for navigation, diagnostics, testing, coverage, and more.910> **TL;DR:** If you use Claude / Cursor / Copilot with Go, `mcp-gopls` gives the AI full LSP powers:11> go-to-definition, references, hover, completion, `go test`, coverage, `go mod tidy`, `govulncheck`, etc.1213141516## Overview1718This MCP server helps AI assistants to:1920- Use LSP to analyze Go workspaces21- Navigate to definitions, references, and workspace symbols22- Format, rename, and inspect code actions without leaving MCP23- Run Go tests, coverage, `go mod tidy`, `govulncheck`, and module graph commands with structured results24- Read workspace resources (overview + go.mod) and consume curated prompts2526> **Status:** Actively developed – used in real projects.27> Tested with Go 1.25.x and `gopls@latest`.2829## Architecture3031This 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.3233The server communicates with [gopls](https://github.com/golang/tools/tree/master/gopls), the official language server for Go, via the Language Server Protocol (LSP).3435## Features3637- **Configurable runtime**: `--workspace`, `--gopls-path`, `--log-level`, `--rpc-timeout`, and `--shutdown-timeout` flags + env vars (`MCP_GOPLS_*`)38- **Structured logging**: Text/JSON logging with slog and optional file output39- **Extended LSP surface**: navigation, diagnostics, formatting, rename, code actions, hover, completion, workspace symbols40- **Test & tooling helpers**: coverage analysis, `go test`, `go mod tidy`, `govulncheck`, `go mod graph`41- **MCP extras**: resources (`resource://workspace/overview`, `resource://workspace/go.mod`) and prompts (`summarize_diagnostics`, `refactor_plan`)42- **Progress streaming**: long-running commands emit `notifications/progress` events so clients can surface status updates4344### Feature comparison: `mcp-gopls` vs built-in `gopls` MCP4546As of `gopls` v0.20.0, the built-in MCP server exposes these tools:47`go_context`, `go_diagnostics`, `go_file_context`, `go_file_diagnostics`,48`go_file_metadata`, `go_package_api`, `go_references`, `go_rename_symbol`,49`go_search`, `go_symbol_references`, `go_workspace`, `go_vulncheck`.5051| Feature / capability | `mcp-gopls` (this project) | Built-in `gopls` MCP |52|----------------------|----------------------------|----------------------|53| Go-to-definition | Yes (`go_to_definition` tool) | No dedicated MCP tool (not in tool list) |54| Find references | Yes (`find_references`) | Yes (`go_references`, `go_symbol_references`) |55| Diagnostics (file / workspace) | Yes (`check_diagnostics`) | Yes (`go_diagnostics`, `go_file_diagnostics`) |56| Hover information | Yes (`get_hover_info`) | No dedicated MCP tool (not in tool list) |57| Completion | Yes (`get_completion`) | No dedicated MCP tool (not in tool list) |58| Formatting | Yes (`format_document`) | No dedicated MCP tool (not in tool list) |59| Rename symbol | Yes (`rename_symbol`) | Yes (`go_rename_symbol`) |60| Code actions | Yes (`list_code_actions`) | No dedicated MCP tool (not in tool list) |61| Workspace symbol search | Yes (`search_workspace_symbols`) | Yes (`go_search`) |62| Package / workspace API/context tools | No dedicated MCP tool | Yes (`go_package_api`, `go_file_context`, `go_file_metadata`, `go_workspace`, `go_context`) |63| Run `go test` | Yes (`run_go_test`) | No MCP tool for running tests |64| Coverage analysis | Yes (`analyze_coverage`) | No MCP tool for coverage |65| `go mod tidy` | Yes (`run_go_mod_tidy`) | No MCP tool for `go mod tidy` |66| `govulncheck` | Yes (`run_govulncheck`) | Yes (`go_vulncheck`) |67| Module graph (`go mod graph`) | Yes (`module_graph`) | No MCP tool for module graph |68| Extra MCP resources | Yes (`resource://workspace/overview`, `resource://workspace/go.mod`) | Not documented as MCP resources |69| Custom MCP prompts | Yes (`summarize_diagnostics`, `refactor_plan`) | Not exposed as MCP prompts (only model instructions) |70| Model instructions shipped with server | No special mechanism (documented in README/docs) | Yes: `gopls mcp -instructions` prints usage workflows |7172If 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.7374If 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.7576> **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.777879## Project Structure8081```bash82.83├── cmd84│ └── mcp-gopls # Application entry point85├── pkg86│ ├── lsp # LSP client to communicate with gopls87│ │ ├── client # LSP client implementation88│ │ └── protocol # LSP protocol types and features89│ ├── server # MCP server90│ └── tools # MCP tools exposing LSP features91```9293## Installation9495```bash96go install github.com/hloiseau/mcp-gopls/v2/cmd/mcp-gopls@latest97```9899## Quick Start1001011. **Install** the server:102103```bash104go install github.com/hloiseau/mcp-gopls/v2/cmd/mcp-gopls@latest105```1061072. **Verify** it's on your `$PATH`:108109```bash110mcp-gopls --help111```1121133. **Configure** your AI client (see examples below for Cursor, Claude Desktop, or GitHub Copilot).114115---116117## Docker / MCP Gateway118119If you prefer to run `mcp-gopls` in a container (for Docker MCP Gateway or other containerized setups), use the official image.120121### Docker run122123```bash124docker run --rm -i \125 -v /absolute/path/to/your/go/project:/workspace \126 ghcr.io/hloiseau/mcp-gopls:latest \127 --workspace /workspace128```129130### docker-mcp.yaml131132Copy `docs/docker-mcp.yaml`, update the bind mount path, then run from that directory:133134```bash135docker mcp gateway run136```137138### Tools catalog metadata139140If your MCP catalog tooling requires a `toolsUrl`, use `docs/tools.json` as a static tool list.141142## Detailed Client Setup143144> **Note:** All clients point to the same command:145> `mcp-gopls --workspace /absolute/path/to/your/go/project`146> The configuration format differs slightly per client, but the binary and arguments remain identical.147148### 1. Connect from Cursor1491501. Open **Settings → MCP Servers → Edit JSON**.1512. Add or update the `mcp-gopls` entry:152153```json154{155 "mcpServers": {156 "mcp-gopls": {157 "command": "mcp-gopls",158 "args": ["--workspace", "/absolute/path/to/your/go/project"],159 "env": {160 "MCP_GOPLS_LOG_LEVEL": "info"161 }162 }163 }164}165```1661673. Run **Developer: Reload Window** so Cursor reconnects.1684. Open the **Tools** drawer in Cursor Chat and enable `mcp-gopls`.169170### 2. Invoke the tools171172| Tool / Prompt | Example request inside Cursor Chat |173|---------------|------------------------------------|174| `go_to_definition` | “Use `go_to_definition` on `pkg/server/server.go:42`.” |175| `find_references` | “Ask the tool for references to `ServeStdio`.” |176| `check_diagnostics` | “Request diagnostics for `cmd/mcp-gopls/main.go`.” |177| `get_hover_info` | “Call `get_hover_info` on `pkg/tools/workspace.go:88`.” |178| `get_completion` | “Trigger completions at `pkg/server/server.go:55`.” |179| `format_document` | “Run the formatter over `pkg/tools/refactor.go`.” |180| `rename_symbol` | “Rename `clientFactory` to `newClientFactory` via the tool.” |181| `list_code_actions` | “List code actions for `pkg/server/server.go:80-90`.” |182| `search_workspace_symbols` | “Search workspace symbols for `NewWorkspaceConfig`.” |183| `analyze_coverage` | “Run `analyze_coverage` for `./pkg/...` with per-function stats.” |184| `run_go_test` | “Execute `run_go_test` on `./cmd/...`.” |185| `run_go_mod_tidy` | “Invoke `run_go_mod_tidy` to sync go.mod.” |186| `run_govulncheck` | “Run `run_govulncheck` and stream findings.” |187| `module_graph` | “Call `module_graph` to inspect dependencies.” |188| `summarize_diagnostics` | “Use the `summarize_diagnostics` prompt on the latest diagnostics.” |189| `refactor_plan` | “Feed `refactor_plan` the diagnostics JSON to plan fixes.” |190191## Client Setup Examples192193### Claude Desktop (macOS, Windows, Linux)1941951. Install `mcp-gopls` and make sure it is on your `$PATH`.1962. Create or edit `claude_desktop_config.json`.197 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`198 - Linux: `~/.config/Claude/claude_desktop_config.json`199 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`2003. Add the server entry:201202```json203{204 "mcpServers": {205 "mcp-gopls": {206 "command": "mcp-gopls",207 "args": ["--workspace", "/absolute/path/to/your/go/project"],208 "env": {209 "MCP_GOPLS_LOG_LEVEL": "info"210 }211 }212 }213}214```215216Restart 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`.”217218### Cursor IDE219220In Cursor open **Settings → MCP Servers → Edit JSON** (this writes to `~/.cursor/config.json` or the project-local override). Add:221222```json223{224 "mcpServers": {225 "mcp-gopls": {226 "command": "mcp-gopls",227 "args": ["--workspace", "/absolute/path/to/your/go/project"]228 }229 }230}231```232233Reload 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`.”234235### GitHub Copilot (Agent Mode)236237GitHub 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:2382391. Update GitHub Copilot (requires VS Code 1.99+), opt into **Agent Mode**.2402. Create `.vscode/mcp.json` in your workspace (or edit the global file shown in the Copilot “Edit config” dialog).2413. Add:242243```json244{245 "servers": {246 "mcp-gopls": {247 "type": "stdio",248 "command": "mcp-gopls",249 "args": ["--workspace", "/absolute/path/to/your/go/project"],250 "env": {251 "MCP_GOPLS_LOG_LEVEL": "warn"252 }253 }254 }255}256```2572584. 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.259260### MCP Inspector / CLI testing261262For quick smoke tests or demos you can use [mark3labs/mcp-inspector](https://github.com/mark3labs/mcp-inspector):263264```bash265npx -y @mark3labs/mcp-inspector \266 --command mcp-gopls \267 --args "--workspace" "/absolute/path/to/your/go/project"268```269270The inspector lets you call each tool/resource/prompt manually, which is handy for debugging server configuration before wiring it into an AI assistant.271272## MCP Tools273274| Tool | Description |275|------|-------------|276| `go_to_definition` | Navigate to the definition of a symbol |277| `find_references` | List all references for a symbol |278| `check_diagnostics` | Fetch cached diagnostics for a file |279| `get_hover_info` | Return hover markdown for a symbol |280| `get_completion` | Return completion labels at a position |281| `format_document` | Return formatting edits for an entire document |282| `rename_symbol` | Return workspace edits for a rename |283| `list_code_actions` | List available code actions for a range |284| `search_workspace_symbols` | Search workspace-wide symbols |285| `analyze_coverage` | Run `go test` with coverage + optional per-function report |286| `run_go_test` | Execute `go test` for a package/pattern |287| `run_go_mod_tidy` | Execute `go mod tidy` |288| `run_govulncheck` | Execute `govulncheck ./...` |289| `module_graph` | Return `go mod graph` output |290291## Progress Notifications292293Long-running tools emit structured `notifications/progress` events so IDEs can show rich status indicators:294295- **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.296- **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.297- Each progress token is now namespaced (e.g., `run_go_test/<rand>`) to avoid “unknown token” errors when multiple tools run concurrently.298299When 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.300301## Prompt Instructions302303Both prompts are accessible from any MCP-aware client via the “Prompts” catalog.304305### `summarize_diagnostics`306307- **When to use:** After `check_diagnostics` or `run_go_test` to turn raw diagnostics into actionable steps.308- **Arguments:** None. The server automatically reads the last diagnostics payload cached by the tools layer.309- **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”).310311### `refactor_plan`312313- **When to use:** You already have a diagnostics JSON array and want a concise change checklist.314- **Arguments:** Requires a `diagnostics` object containing the raw Go diagnostics (the same payload returned by `check_diagnostics`).315- **Example invocation payload:**316317```json318{319 "diagnostics": [320 {321 "uri": "file:///path/to/pkg/tools/workspace.go",322 "range": {"start": {"line": 12, "character": 5}, "end": {"line": 12, "character": 25}},323 "severity": 1,324 "message": "unused variable testHelper"325 }326 ]327}328```329330The prompt responds with a numbered set of refactor steps plus suggested validation commands (`go test`, `analyze_coverage`, etc.).331332## Configuration333334The server supports various configuration options via command-line flags and environment variables:335336### Command-Line Flags337338| Flag | Default | Description |339|-----------------------|---------|------------------------------------------------|340| `--workspace` | `.` | Absolute path to your Go project root |341| `--gopls-path` | `gopls` | Path to the gopls binary |342| `--log-level` | `info` | Log level (`debug`, `info`, `warn`, `error`) |343| `--rpc-timeout` | `30s` | RPC timeout for LSP calls |344| `--shutdown-timeout` | `5s` | Timeout for graceful shutdown |345346### Environment Variables347348All flags can be set via environment variables with the `MCP_GOPLS_` prefix:349350| Environment Variable | Equivalent Flag | Description |351|---------------------------|-----------------------|------------------------------------------------|352| `MCP_GOPLS_WORKSPACE` | `--workspace` | Absolute path to your Go project root |353| `MCP_GOPLS_GOPLS_PATH` | `--gopls-path` | Path to the gopls binary |354| `MCP_GOPLS_LOG_LEVEL` | `--log-level` | Log level (`debug`, `info`, `warn`, `error`) |355| `MCP_GOPLS_RPC_TIMEOUT` | `--rpc-timeout` | RPC timeout for LSP calls (e.g., `30s`, `1m`) |356| `MCP_GOPLS_SHUTDOWN_TIMEOUT` | `--shutdown-timeout` | Timeout for graceful shutdown |357358Command-line flags take precedence over environment variables.359360## Troubleshooting361362- **“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.363- **“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.364- **“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.365- **`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.366367## Usage Example368369Using the server with AI assistants that support MCP:370371```Markdown372# Ask the AI to get information about the code373Can you find the definition of the `ServeStdio` function in this project?374375# Ask for diagnostics376Are there any errors in my main.go file?377378# Ask for information about a symbol379What does the Context.WithTimeout function do in Go?380```381382## Development383384```bash385git clone https://github.com/hloiseau/mcp-gopls.git386cd mcp-gopls387go mod tidy388go test ./...389go build ./cmd/mcp-gopls390```391392Table-driven tests live under `pkg/tools` and CI runs via `.github/workflows/ci.yml`.393394### Documentation395396- `docs/usage.md` – quickstart and tool catalog walkthrough397- Workspace resources expose `resource://workspace/overview` and `resource://workspace/go.mod`398- Prompts (`summarize_diagnostics`, `refactor_plan`) help assistants produce consistent outputs399400## Contributing401402PRs and issues are welcome!403404- Check [open issues](https://github.com/hloiseau/mcp-gopls/issues) or file a new one if you hit a bug or want a feature.405- Run `go test ./...` before opening a PR.406- For bigger changes (new tools, protocol changes), please open a design issue first so we can discuss the approach.407408All contributions should maintain test coverage and adhere to Go best practices. See the [Development](#development) section for setup instructions.409410## Prerequisites411412- Go 1.25+ (tested with `go1.25.4`)413- `gopls` installed (`go install golang.org/x/tools/gopls@latest`)414- Optional: `govulncheck` (`go install golang.org/x/vuln/cmd/govulncheck@latest`)415- 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`.416417## Integration with Ollama418419This MCP server can be used with any tool that supports the MCP protocol. For Ollama integration:4204211. Make sure Ollama is running4222. The MCP server runs independently and communicates through stdin/stdout4233. Configure your client to use the MCP server as a tool provider424425## License426427Apache License 2.0428
Full transparency — inspect the skill content before installing.