# Mcp Gopls

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

- **Type:** MCP server
- **Install:** `agentstack add mcp-hloiseau-mcp-gopls`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hloiseau](https://agentstack.voostack.com/s/hloiseau)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [hloiseau](https://github.com/hloiseau)
- **Source:** https://github.com/hloiseau/mcp-gopls
- **Website:** https://github.com/hloiseau/mcp-gopls/blob/main/docs/usage.md

## Install

```sh
agentstack add mcp-hloiseau-mcp-gopls
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcp-gopls – MCP server for Go (gopls)

[](LICENSE)

[](https://github.com/hloiseau/mcp-gopls/actions)
[](https://ghcr.io/hloiseau/mcp-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](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.

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

## 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`.

| Feature / capability | `mcp-gopls` (this project) | Built-in `gopls` MCP |
|----------------------|----------------------------|----------------------|
| Go-to-definition | Yes (`go_to_definition` tool) | No dedicated MCP tool (not in tool list) |
| Find references | Yes (`find_references`) | Yes (`go_references`, `go_symbol_references`) |
| Diagnostics (file / workspace) | Yes (`check_diagnostics`) | Yes (`go_diagnostics`, `go_file_diagnostics`) |
| Hover information | Yes (`get_hover_info`) | No dedicated MCP tool (not in tool list) |
| Completion | Yes (`get_completion`) | No dedicated MCP tool (not in tool list) |
| Formatting | Yes (`format_document`) | No dedicated MCP tool (not in tool list) |
| Rename symbol | Yes (`rename_symbol`) | Yes (`go_rename_symbol`) |
| Code actions | Yes (`list_code_actions`) | No dedicated MCP tool (not in tool list) |
| Workspace symbol search | Yes (`search_workspace_symbols`) | Yes (`go_search`) |
| Package / workspace API/context tools | No dedicated MCP tool | Yes (`go_package_api`, `go_file_context`, `go_file_metadata`, `go_workspace`, `go_context`) |
| Run `go test` | Yes (`run_go_test`) | No MCP tool for running tests |
| Coverage analysis | Yes (`analyze_coverage`) | No MCP tool for coverage |
| `go mod tidy` | Yes (`run_go_mod_tidy`) | No MCP tool for `go mod tidy` |
| `govulncheck` | Yes (`run_govulncheck`) | Yes (`go_vulncheck`) |
| Module graph (`go mod graph`) | Yes (`module_graph`) | No MCP tool for module graph |
| Extra MCP resources | Yes (`resource://workspace/overview`, `resource://workspace/go.mod`) | Not documented as MCP resources |
| Custom MCP prompts | Yes (`summarize_diagnostics`, `refactor_plan`) | Not exposed as MCP prompts (only model instructions) |
| Model instructions shipped with server | No special mechanism (documented in README/docs) | Yes: `gopls mcp -instructions` prints usage workflows |

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

```bash
.
├── 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

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

## Quick Start

1. **Install** the server:

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

2. **Verify** it's on your `$PATH`:

```bash
mcp-gopls --help
```

3. **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

```bash
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:

```bash
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:

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

3. Run **Developer: Reload Window** so Cursor reconnects.
4. Open the **Tools** drawer in Cursor Chat and enable `mcp-gopls`.

### 2. Invoke the tools

| Tool / Prompt | Example request inside Cursor Chat |
|---------------|------------------------------------|
| `go_to_definition` | “Use `go_to_definition` on `pkg/server/server.go:42`.” |
| `find_references` | “Ask the tool for references to `ServeStdio`.” |
| `check_diagnostics` | “Request diagnostics for `cmd/mcp-gopls/main.go`.” |
| `get_hover_info` | “Call `get_hover_info` on `pkg/tools/workspace.go:88`.” |
| `get_completion` | “Trigger completions at `pkg/server/server.go:55`.” |
| `format_document` | “Run the formatter over `pkg/tools/refactor.go`.” |
| `rename_symbol` | “Rename `clientFactory` to `newClientFactory` via the tool.” |
| `list_code_actions` | “List code actions for `pkg/server/server.go:80-90`.” |
| `search_workspace_symbols` | “Search workspace symbols for `NewWorkspaceConfig`.” |
| `analyze_coverage` | “Run `analyze_coverage` for `./pkg/...` with per-function stats.” |
| `run_go_test` | “Execute `run_go_test` on `./cmd/...`.” |
| `run_go_mod_tidy` | “Invoke `run_go_mod_tidy` to sync go.mod.” |
| `run_govulncheck` | “Run `run_govulncheck` and stream findings.” |
| `module_graph` | “Call `module_graph` to inspect dependencies.” |
| `summarize_diagnostics` | “Use the `summarize_diagnostics` prompt on the latest diagnostics.” |
| `refactor_plan` | “Feed `refactor_plan` the diagnostics JSON to plan fixes.” |

## 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:

```json
{
  "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:

```json
{
  "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](https://docs.github.com/en/copilot/customizing-copilot/extending-copilot-chat-with-mcp)). 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:

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

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.

### MCP Inspector / CLI testing

For quick smoke tests or demos you can use [mark3labs/mcp-inspector](https://github.com/mark3labs/mcp-inspector):

```bash
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

| Tool | Description |
|------|-------------|
| `go_to_definition` | Navigate to the definition of a symbol |
| `find_references` | List all references for a symbol |
| `check_diagnostics` | Fetch cached diagnostics for a file |
| `get_hover_info` | Return hover markdown for a symbol |
| `get_completion` | Return completion labels at a position |
| `format_document` | Return formatting edits for an entire document |
| `rename_symbol` | Return workspace edits for a rename |
| `list_code_actions` | List available code actions for a range |
| `search_workspace_symbols` | Search workspace-wide symbols |
| `analyze_coverage` | Run `go test` with coverage + optional per-function report |
| `run_go_test` | Execute `go test` for a package/pattern |
| `run_go_mod_tidy` | Execute `go mod tidy` |
| `run_govulncheck` | Execute `govulncheck ./...` |
| `module_graph` | Return `go mod graph` output |

## Progress Notifications

Long-running tools emit structured `notifications/progress` events so IDEs can show rich status indicators:

- **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.
- **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.
- Each progress token is now namespaced (e.g., `run_go_test/`) to avoid “unknown token” errors when multiple tools run concurrently.

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.

## Prompt Instructions

Both prompts are accessible from any MCP-aware client via the “Prompts” catalog.

### `summarize_diagnostics`

- **When to use:** After `check_diagnostics` or `run_go_test` to turn raw diagnostics into actionable steps.
- **Arguments:** None. The server automatically reads the last diagnostics payload cached by the tools layer.
- **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”).

### `refactor_plan`

- **When to use:** You already have a diagnostics JSON array and want a concise change checklist.
- **Arguments:** Requires a `diagnostics` object containing the raw Go diagnostics (the same payload returned by `check_diagnostics`).
- **Example invocation payload:**

```json
{
  "diagnostics": [
    {
      "uri": "file:///path/to/pkg/tools/workspace.go",
      "range": {"start": {"line": 12, "character": 5}, "end": {"line": 12, "character": 25}},
      "severity": 1,
      "message": "unused variable testHelper"
    }
  ]
}
```

The prompt responds with a numbered set of refactor steps plus suggested validation commands (`go test`, `analyze_coverage`, etc.).

## Configuration

The server supports various configuration options via command-line flags and environment variables:

### Command-Line Flags

| Flag                  | Default | Description                                    |
|-----------------------|---------|------------------------------------------------|
| `--workspace`         | `.`     | Absolute path to your Go project root          |
| `--gopls-path`        | `gopls` | Path to the gopls binary                       |
| `--log-level`         | `info`  | Log level (`debug`, `info`, `warn`, `error`)   |
| `--rpc-timeout`       | `30s`   | RPC timeout for LSP calls                      |
| `--shutdown-timeout`  | `5s`    | Timeout for graceful shutdown                  |

### Environment Variables

All flags can be set via environment variables with the `MCP_GOPLS_` prefix:

| Environment Variable       | Equivalent Flag       | Description                                    |
|---------------------------|-----------------------|------------------------------------------------|
| `MCP_GOPLS_WORKSPACE`     | `--workspace`         | Absolute path to your Go project root          |
| `MCP_GOPLS_GOPLS_PATH`    | `--gopls-path`        | Path to the gopls binary                       |
| `MCP_GOPLS_LOG_LEVEL`     | `--log-level`         | Log level (`debug`, `info`, `warn`, `error`)   |
| `MCP_GOPLS_RPC_TIMEOUT`   | `--rpc-timeout`       | RPC timeout for LSP calls (e.g., `30s`, `1m`)  |
| `MCP_GOPLS_SHUTDOWN_TIMEOUT` | `--shutdown-timeout` | Timeout for graceful shutdown                |

Command-line flags take precedence over environment variables.

## Troubleshooting

- **“column is beyond end of line”** – gopls could not map the provided position. Confirm the file is saved and the p

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hloiseau](https://github.com/hloiseau)
- **Source:** [hloiseau/mcp-gopls](https://github.com/hloiseau/mcp-gopls)
- **License:** Apache-2.0
- **Homepage:** https://github.com/hloiseau/mcp-gopls/blob/main/docs/usage.md

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-hloiseau-mcp-gopls
- Seller: https://agentstack.voostack.com/s/hloiseau
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.