Gopls

mcp-gopls – MCP server for Go (gopls)

A Model Context Protocol (MCP) server that lets AI assistants use Go’s LSP (gopls) for navigation, diagnostics, testing, coverage, and more.

TL;DR: If you use Claude / Cursor / Copilot with Go, mcp-gopls gives the AI full LSP powers: go-to-definition, references, hover, completion, go test, coverage, go mod tidy, govulncheck, etc.

Overview

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 module graph commands with structured results
• Read workspace resources (overview + go.mod) and consume curated prompts

Status: Actively developed – used in real projects.
Tested with Go 1.25.x and gopls@latest.

Architecture

This project uses the mark3labs/mcp-go library to implement the Model Context Protocol. The MCP integration enables seamless communication between AI assistants and Go tools.

The server communicates with gopls, the official language server for Go, via the Language Server Protocol (LSP).

Features

• Configurable runtime: --workspace, --gopls-path, --log-level, --rpc-timeout, and --shutdown-timeout flags + env vars (MCP_GOPLS_*)
• Structured logging: Text/JSON logging with slog and optional file output
• Extended LSP surface: navigation, diagnostics, formatting, rename, code actions, hover, completion, workspace symbols
• Test & tooling helpers: coverage analysis, go test, go mod tidy, govulncheck, go mod graph
• MCP extras: resources (resource://workspace/overview, resource://workspace/go.mod) and prompts (summarize_diagnostics, refactor_plan)
• Progress streaming: long-running commands emit notifications/progress events so clients can surface status updates

Feature comparison: mcp-gopls vs built-in gopls MCP

As of gopls v0.20.0, the built-in MCP server exposes these tools: go_context, go_diagnostics, go_file_context, go_file_diagnostics, go_file_metadata, go_package_api, go_references, go_rename_symbol, go_search, go_symbol_references, go_workspace, go_vulncheck.

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.

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.

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.

Project Structure

.
├── cmd
│   └── mcp-gopls        # Application entry point
├── pkg
│   ├── lsp             # LSP client to communicate with gopls
│   │   ├── client      # LSP client implementation
│   │   └── protocol    # LSP protocol types and features
│   ├── server          # MCP server
│   └── tools           # MCP tools exposing LSP features

Installation

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

Quick Start

1. Install the server:

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

1. Verify it's on your $PATH:

mcp-gopls --help

1. Configure your AI client (see examples below for Cursor, Claude Desktop, or GitHub Copilot).

Docker / MCP Gateway

If you prefer to run mcp-gopls in a container (for Docker MCP Gateway or other containerized setups), use the official image.

Docker run

docker run --rm -i \
  -v /absolute/path/to/your/go/project:/workspace \
  ghcr.io/hloiseau/mcp-gopls:latest \
  --workspace /workspace

docker-mcp.yaml

Copy docs/docker-mcp.yaml, update the bind mount path, then run from that directory:

docker mcp gateway run

Tools catalog metadata

If your MCP catalog tooling requires a toolsUrl, use docs/tools.json as a static tool list.

Detailed Client Setup

Note: All clients point to the same command:
mcp-gopls --workspace /absolute/path/to/your/go/project
The configuration format differs slightly per client, but the binary and arguments remain identical.

1. Connect from Cursor

1. Open Settings → MCP Servers → Edit JSON.
2. Add or update the mcp-gopls entry:

{
  "mcpServers": {
    "mcp-gopls": {
      "command": "mcp-gopls",
      "args": ["--workspace", "/absolute/path/to/your/go/project"],
      "env": {
        "MCP_GOPLS_LOG_LEVEL": "info"
      }
    }
  }
}

1. Run Developer: Reload Window so Cursor reconnects.
2. Open the Tools drawer in Cursor Chat and enable mcp-gopls.

2. Invoke the tools

Client Setup Examples

Claude Desktop (macOS, Windows, Linux)

1. Install mcp-gopls and make sure it is on your $PATH.
2. Create or edit claude_desktop_config.json.
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Add the server entry:

{
  "mcpServers": {
    "mcp-gopls": {
      "command": "mcp-gopls",
      "args": ["--workspace", "/absolute/path/to/your/go/project"],
      "env": {
        "MCP_GOPLS_LOG_LEVEL": "info"
      }
    }
  }
}

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.”

Cursor IDE

In Cursor open Settings → MCP Servers → Edit JSON (this writes to ~/.cursor/config.json or the project-local override). Add:

{
  "mcpServers": {
    "mcp-gopls": {
      "command": "mcp-gopls",
      "args": ["--workspace", "/absolute/path/to/your/go/project"]
    }
  }
}

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.”

GitHub Copilot (Agent Mode)

GitHub Copilot’s Agent Mode can talk to local MCP servers across VS Code, JetBrains IDEs, Eclipse, and Xcode (docs). To wire mcp-gopls in VS Code:

1. Update GitHub Copilot (requires VS Code 1.99+), opt into Agent Mode.
2. Create .vscode/mcp.json in your workspace (or edit the global file shown in the Copilot “Edit config” dialog).
3. Add:

{
  "servers": {
    "mcp-gopls": {
      "type": "stdio",
      "command": "mcp-gopls",
      "args": ["--workspace", "/absolute/path/to/your/go/project"],
      "env": {
        "MCP_GOPLS_LOG_LEVEL": "warn"
      }
    }
  }
}

1. 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.

MCP Inspector / CLI testing

For quick smoke tests or demos you can use mark3labs/mcp-inspector:

npx -y @mark3labs/mcp-inspector \
  --command mcp-gopls \
  --args "--workspace" "/absolute/path/to/your/go/project"

The inspector lets you call each tool/resource/prompt manually, which is handy for debugging server configuration before wiring it into an AI assistant.

MCP Tools

…