home / mcp / mcp-gopls mcp server

mcp-gopls MCP Server

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

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "hloiseau-mcp-gopls": {
      "command": "mcp-gopls",
      "args": [
        "--workspace",
        "/absolute/path/to/your/go/project"
      ],
      "env": {
        "MCP_GOPLS_LOG_LEVEL": "info",
        "MCP_GOPLS_WORKSPACE": "\"/path/to/project\"",
        "MCP_GOPLS_GOPLS_PATH": "\"/usr/local/bin/gopls\"",
        "MCP_GOPLS_RPC_TIMEOUT": "\"30s\"",
        "MCP_GOPLS_SHUTDOWN_TIMEOUT": "\"5s\""
      }
    }
  }
}

You can run a Go MCP server named mcp-gopls that lets AI assistants leverage Go tooling through gopls. This server exposes extensive LSP-powered capabilities for navigation, diagnostics, testing, coverage, and workspace inspection, enabling seamless interaction with Go code from AI copilots and IDE integrations.

How to use

Connect to mcp-gopls from your MCP-aware client to access Go language features through the LSP surface and the MCP tools. With this server you can navigate to definitions, find references, view hover information, trigger completions, format documents, rename symbols, list code actions, search workspace symbols, run Go tests and coverage, tidy modules, perform vulnerability checks, and generate a module graph. You also receive curated workspace resources and prompts to help with diagnostics and refactoring.

How to install

Prerequisites you need before installing this server:

Go 1.25+ (tested with go1.25.4) must be installed on your system.

GOPATH-aware Go tooling is expected, including gopls (Go language server) installed via the Go toolchain.

Step-by-step commands to install and run the MCP server locally:

Step 1: Install the server

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

Step 2: Verify the server is on your PATH

mcp-gopls --help

Step 3: Run or configure the server

You can start the server directly from the command line and point clients to the workspace you want to analyze.

Optional: Docker usage

If you prefer containerized execution, run the server with Docker using your workspace mounted into the container.

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

Available tools

go_to_definition

Navigate to the definition of a symbol in the workspace using the MCP tool surface.

find_references

List all references to a symbol across the workspace.

check_diagnostics

Fetch cached or up-to-date diagnostics for a file.

get_hover_info

Return hover information for a symbol, including type and documentation snippets.

get_completion

Provide completion suggestions at a given code position.

format_document

Return formatting edits to apply to an entire document.

rename_symbol

Compute workspace edits to rename a symbol across the project.

list_code_actions

List available code actions that can be applied to a code range.

search_workspace_symbols

Search for symbols across the entire workspace.

analyze_coverage

Run tests with coverage and generate optional per-function reports.

run_go_test

Execute go test for a package or pattern.

run_go_mod_tidy

Run go mod tidy to synchronize module dependencies.

run_govulncheck

Execute vulnerability checks across the workspace.

module_graph

Return the output of go mod graph to visualize dependencies.