Gopls: Model Context Protocol support

Gopls includes an experimental built-in server for the Model Context Protocol (MCP), allowing it to expose a subset of its functionality to AI assistants in the form of MCP tools.

Running the MCP server

There are two modes for running this server: ‘attached’ and ‘detached’. In attached mode, the MCP server operates in the context of an active gopls LSP session, and so is able to share memory with your LSP session and observe the current unsaved buffer state. In detached mode, gopls interacts with a headless LSP session, and therefore only sees saved files on disk.

Attached mode

To use the ‘attached’ mode, run gopls with the -mcp.listen flag. For example:

gopls serve -mcp.listen=localhost:8092

This exposes an HTTP based MCP server using the server-sent event transport (SSE), available at http://localhost:8092/sessions/1 (assuming you have only one session on your gopls instance).

Detached mode

To use the ‘detached’ mode, run the mcp subcommand:

gopls mcp

This runs a standalone gopls instance that speaks MCP over stdin/stdout.

Instructions to the model

This gopls MCP server includes model instructions for its usage, describing workflows for interacting with Go code using its available tools. These instructions are automatically published during the MCP server initialization, but you may want to also load them as additional context in your AI-assisted session, to emphasize their importance. The -instructions flag causes them to be printed, so that you can do, for example:

gopls mcp -instructions > /path/to/contextFile.md

Coding assistant setup

To use the gopls MCP server with an LLM-based coding assistant, you need to configure the assistant’s MCP client to talk to gopls. Below are guides for popular assistants.

First ensure that gopls v0.20 or higher is installed and available in your $PATH. Use this command to install the latest version:

$ go install golang.org/x/tools/gopls@latest

Gemini CLI

For Gemini CLI, add the following configuration to $HOME/.gemini/extensions/go/gemini-extension.json:

{
  "name": "go",
  "version": "0.0.1",
  "mcpServers": {
    "go": {
      "command": "gopls",
      "args": ["mcp"]
    }
  },
  "contextFileName": "GEMINI.md"
}

Then run this command to emit the model instructions:

$ gopls mcp -instructions > ~/.gemini/extensions/go/GEMINI.md

To verify the connection, use the /mcp list command in your Gemini session to view available tools. Alternatively, run gemini mcp list from your shell to inspect active MCP servers and connection status.

Claude Code

For Claude Code, run the following command to add gopls as an MCP server:

$ claude mcp add gopls -- gopls mcp

To verify the connection and explore available tools:

• Type /mcp inside your Claude session to view the list of tools offering.
• Run claude mcp list to inspect currently active MCP servers.
• Run claude mcp get gopls to inspect the configuration details of the server.

Security considerations

The gopls MCP server is a wrapper around the functionality ordinarily exposed by gopls through the Language Server Protocol (LSP). As such, gopls’ tools may perform any of the operations gopls normally performs, including:

• reading files from the file system, and returning their contents in tool results (such as when providing context);
• executing the go command to load package information, which may result in calls to https://proxy.golang.org to download Go modules, and writes to go caches;
• writing to gopls’ cache or persistent configuration files; and
• uploading weekly telemetry data if you have opted in to Go telemetry.

The gopls MCP server does not perform any operations not already performed by gopls in an ordinary IDE session. Like most LSP servers, gopls does not generally write directly to your source tree, though it may instruct the client to apply edits. Nor does it make arbitrary requests over the network, though it may make narrowly scoped requests to certain services such as the Go module mirror or the Go vulnerability database, which can’t readily be exploited as a vehicle for exfiltration by a confused agent. Nevertheless, these capabilities may require additional consideration when used as part of an AI-enabled system.