MCP LSP Go

mcp-gopls – Go 用 MCP サーバー（gopls）

AI アシスタントが Go の LSP（gopls）を使って、コードのナビゲーション、診断、テスト、カバレッジなどを行える Model Context Protocol（MCP）サーバーです。

要約： Go で Claude／Cursor／Copilot を使う場合、mcp-gopls により AI は LSP の機能をフル活用できます。 定義への移動、参照、ホバー、補完、go test、カバレッジ、go mod tidy、govulncheck などに対応します。

概要

この MCP サーバーを使うと、AI アシスタントは次のことができます。

• LSP を使って Go ワークスペースを分析する
• 定義、参照、ワークスペースシンボルに移動する
• MCP を離れずに、コードのフォーマット、名前変更、コードアクションの確認を行う
• Go のテスト、カバレッジ、go mod tidy、govulncheck、モジュールグラフのコマンドを実行し、構造化された結果を取得する
• ワークスペースのリソース（概要＋go.mod）を読み取り、厳選されたプロンプトを利用する

ステータス： 継続的に開発中です。実際のプロジェクトで使用されています。
Go 1.25.x および gopls@latest でテスト済みです。

アーキテクチャ

このプロジェクトでは、Model Context Protocol を実装するために mark3labs/mcp-go ライブラリを使用しています。MCP 統合により、AI アシスタントと Go ツール間のシームレスな通信が可能になります。

サーバーは、Go の公式言語サーバーである gopls と、Language Server Protocol（LSP）を介して通信します。

機能

• 実行時設定：--workspace、--gopls-path、--log-level、--rpc-timeout、--shutdown-timeout フラグと環境変数（MCP_GOPLS_*）
• 構造化ログ：slog によるテキスト／JSON ログと、任意のファイル出力
• 拡張 LSP 機能：ナビゲーション、診断、フォーマット、名前変更、コードアクション、ホバー、補完、ワークスペースシンボル
• テストとツールのヘルパー：カバレッジ分析、go test、go mod tidy、govulncheck、go mod graph
• MCP の追加機能：リソース（resource://workspace/overview、resource://workspace/go.mod）とプロンプト（summarize_diagnostics、refactor_plan）
• 進捗のストリーミング：長時間実行されるコマンドは notifications/progress イベントを発行し、クライアントにステータスの更新を表示できるようにします

機能比較：mcp-gopls と組み込みの gopls MCP

gopls v0.20.0 時点で、組み込みの MCP サーバーは次のツールを公開しています： 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。

機能 / 能力	mcp-gopls（このプロジェクト）	組み込みの gopls MCP
定義へ移動	あり（go_to_definition ツール）	専用の MCP ツールなし（ツール一覧にありません）
参照の検索	あり（find_references）	あり（go_references、go_symbol_references）
診断（ファイル / ワークスペース）	あり（check_diagnostics）	あり（go_diagnostics、go_file_diagnostics）
ホバー情報	あり（get_hover_info）	専用の MCP ツールなし（ツール一覧にありません）
補完	あり（get_completion）	専用の MCP ツールなし（ツール一覧にありません）
フォーマット	あり（format_document）	専用の MCP ツールなし（ツール一覧にありません）
シンボル名の変更	あり（rename_symbol）	あり（go_rename_symbol）
コードアクション	あり（list_code_actions）	専用の MCP ツールなし（ツール一覧にありません）
ワークスペースのシンボル検索	あり（search_workspace_symbols）	あり（go_search）
パッケージ / ワークスペース API・コンテキストツール	専用の MCP ツールなし	あり（go_package_api、go_file_context、go_file_metadata、go_workspace、go_context）
go test の実行	あり（run_go_test）	テスト実行用の MCP ツールなし
カバレッジ分析	あり（analyze_coverage）	カバレッジ用の MCP ツールなし
go mod tidy	あり（run_go_mod_tidy）	go mod tidy 用の MCP ツールなし
govulncheck	あり（run_govulncheck）	あり（go_vulncheck）
モジュールグラフ（go mod graph）	あり（module_graph）	モジュールグラフ用の MCP ツールなし
追加の MCP リソース	あり（resource://workspace/overview、resource://workspace/go.mod）	MCP リソースとしては文書化されていません
カスタム MCP プロンプト	あり（summarize_diagnostics、refactor_plan）	MCP プロンプトとしては公開されていません（モデルへの指示のみ）
サーバーに同梱されるモデルへの指示	特別な仕組みなし（README / ドキュメントに記載）	あり：gopls mcp -instructions で使用ワークフローを表示

MCP から LSP のような編集機能とツール一式（定義、ホバー、補完、フォーマット、名前変更、コードアクション、go test、カバレッジ、go mod tidy、モジュールグラフ）を利用したい場合、mcp-gopls のほうが機能が豊富です。

追加のバイナリなしで、主に読み取り専用の内省ツール（診断、シンボル検索、参照、パッケージ API、ワークスペース / ファイルのコンテキスト、vulncheck）を使いたい場合は、組み込みの gopls MCP で十分です。

注： 組み込みの gopls MCP サーバーは現在も実験的機能として扱われており、ツールセットは今後変更される可能性があります。この比較は gopls v0.20.x 時点の内容です。

プロジェクト構成

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

インストール

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

クイックスタート

1. サーバーをインストールします：

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

2. $PATH に含まれていることを確認します：

mcp-gopls --help

3. AI クライアントを設定します（Cursor、Claude Desktop、GitHub Copilot の例は以下を参照してください）。

---

Docker / MCP Gateway

mcp-gopls をコンテナー内で実行する場合（Docker MCP Gateway やその他のコンテナー環境など）は、公式イメージを使用してください。

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

docs/docker-mcp.yaml をコピーしてバインドマウントのパスを更新し、そのディレクトリから実行します：

docker mcp gateway run

ツールカタログのメタデータ

MCP カタログのツールで toolsUrl が必要な場合は、静的なツール一覧として docs/tools.json を使用してください。

クライアントの詳細な設定

注： すべてのクライアントで同じコマンドを指定します：
mcp-gopls --workspace /absolute/path/to/your/go/project
設定形式はクライアントごとに多少異なりますが、バイナリと引数は同じです。

1. Cursor から接続する

1. Settings → MCP Servers → Edit JSON を開きます。
2. mcp-gopls のエントリーを追加または更新します：

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

3. Developer: Reload Window を実行して、Cursor を再接続します。
4. Cursor Chat の Tools ドロワーを開き、mcp-gopls を有効にします。

2. ツールを呼び出す

ツール／プロンプト	Cursor Chat でのリクエスト例
go_to_definition	「pkg/server/server.go:42 で go_to_definition を使ってください。」
find_references	「ServeStdio の参照をツールに問い合わせてください。」
check_diagnostics	「cmd/mcp-gopls/main.go の診断をリクエストしてください。」
get_hover_info	「pkg/tools/workspace.go:88 で get_hover_info を呼び出してください。」
get_completion	「pkg/server/server.go:55 で補完を実行してください。」
format_document	「pkg/tools/refactor.go にフォーマッターを実行してください。」
rename_symbol	「ツールを使って clientFactory を newClientFactory に名前変更してください。」
list_code_actions	「pkg/server/server.go:80-90 のコードアクションを一覧表示してください。」
search_workspace_symbols	「ワークスペースのシンボルで NewWorkspaceConfig を検索してください。」
analyze_coverage	「関数ごとの統計を含めて、./pkg/... に analyze_coverage を実行してください。」
run_go_test	「./cmd/... で run_go_test を実行してください。」
run_go_mod_tidy	「go.mod を同期するために run_go_mod_tidy を呼び出してください。」
run_govulncheck	「run_govulncheck を実行し、検出結果をストリーミングしてください。」
module_graph	「依存関係を調べるために module_graph を呼び出してください。」
summarize_diagnostics	「最新の診断に summarize_diagnostics プロンプトを使ってください。」
refactor_plan	「修正を計画するため、診断 JSON を refactor_plan に渡してください。」

クライアントのセットアップ例

Claude Desktop（macOS、Windows、Linux）

1. mcp-gopls をインストールし、$PATH に含まれていることを確認します。
2. 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. サーバーエントリーを追加します。

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

Claude Desktop を再起動してチャットを開き、mcp-gopls ツールへの接続を依頼してください（サーバーが検出されると、Claude に「Tools」タブが表示されます）。一般的なプロンプトには、「cmd/api/server.go の診断を一覧表示してください」や「userService を accountService に名前変更してください」などがあります。

Cursor IDE

Cursor で Settings → MCP Servers → Edit JSON を開きます（この操作により ~/.cursor/config.json またはプロジェクトローカルのオーバーライドに書き込まれます）。次を追加します。

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

Cursor を再読み込みする（または Developer: Reload Window コマンドを実行する）と、サーバーが「Tools」ドロワーに表示されます。これで Cursor Chat に「カバレッジ付きで go test ./pkg/server を実行してください」や「pkg/tools/tests.go:42 のホバー情報を表示してください」などと依頼できます。

GitHub Copilot（エージェントモード）

GitHub Copilot のエージェントモードは、VS Code、JetBrains IDE、Eclipse、Xcode でローカル MCP サーバーと通信できます（ドキュメント）。VS Code で mcp-gopls を接続する手順は次のとおりです。

1. GitHub Copilot を更新し（VS Code 1.99 以降が必要）、Agent Mode を有効にします。
2. ワークスペースに .vscode/mcp.json を作成します（または、Copilot の「Edit config」ダイアログに表示されるグローバルファイルを編集します）。
3. 次を追加します。

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

4. Copilot が新しいツールを検出できるよう、エージェントモードを再読み込みします（オフ／オンを切り替えます）。これでチャットの「Tools」ピッカーに、すべての MCP アクション（run_go_test、run_govulncheck など）が表示されます。JetBrains やその他の IDE では、Copilot の設定パネルを通じて同じ JSON スキーマを使用できます。

MCP Inspector／CLI テスト

簡単なスモークテストやデモには、mark3labs/mcp-inspector を使用できます。

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

Inspector では各ツール／リソース／プロンプトを手動で呼び出せるため、AI アシスタントに接続する前にサーバーの設定をデバッグするのに便利です。

MCP ツール

ツール	説明
go_to_definition	シンボルの定義へ移動します
find_references	シンボルへの参照をすべて一覧表示します
check_diagnostics	ファイルのキャッシュ済み診断情報を取得します
get_hover_info	シンボルのホバーマークダウンを返します
get_completion	指定位置での補完候補ラベルを返します
format_document	ドキュメント全体のフォーマット編集を返します
rename_symbol	名前変更のワークスペース編集を返します
list_code_actions	範囲で利用可能なコードアクションを一覧表示します
search_workspace_symbols	ワークスペース全体のシンボルを検索します
analyze_coverage	カバレッジと任意の関数別レポートを付けて go test を実行します
run_go_test	パッケージまたはパターンに対して go test を実行します
run_go_mod_tidy	go mod tidy を実行します
run_govulncheck	govulncheck ./... を実行します
module_graph	go mod graph の出力を返します

進行状況通知

実行時間の長いツールは、構造化された notifications/progress イベントを送信するため、IDE に詳細なステータスインジケーターを表示できます。

• ストリーミング進行状況（run_go_test、analyze_coverage、run_govulncheck、run_go_mod_tidy）では、ログ行とパーセンテージの更新が段階的に転送されます。Cursor ではこれらがライブログとして表示されます。
• 開始／完了イベントのみ（go_to_definition、find_references、rename_symbol など）では、UI にスピナーを表示できるよう、すぐに「開始」イベントを送信し、その後、最終結果を含む完了ペイロードを送信します。
• 各進行状況トークンに名前空間が付くようになりました（例：run_go_test/<rand>）。複数のツールを同時に実行したときに「不明なトークン」エラーが発生するのを防ぎます。

新しいツールを統合する場合、基盤となる LSP／golang コマンドから意味のある途中経過が出力される場合にのみストリーミングモードを有効にしてください。それ以外の場合は、不要な通知を最小限に抑えるため、軽量な開始／完了フローを使用してください。

プロンプトの説明

どちらのプロンプトも、「Prompts」カタログから MCP 対応クライアントで利用できます。

summarize_diagnostics

• 使用するタイミング： 生の診断情報を実行可能な手順に変換するため、check_diagnostics または run_go_test の実行後に使用します。
• 引数： ありません。サーバーはツールレイヤーがキャッシュした最新の診断ペイロードを自動的に読み取ります。
• 一般的なワークフロー： check_diagnostics → 返された配列をプロンプト入力欄にコピーします（「Use last result」を選択すると、Cursor の UI が自動的に貼り付けます）。

refactor_plan

• 使用するタイミング： 診断情報の JSON 配列がすでにあり、簡潔な変更チェックリストが必要な場合に使用します。
• 引数： 生の Go 診断情報を含む diagnostics オブジェクトが必要です（check_diagnostics が返すものと同じペイロードです）。
• 呼び出しペイロードの例：

{
  "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"
    }
  ]
}

このプロンプトは、番号付きのリファクタリング手順と、推奨される検証コマンド（go test、analyze_coverage など）を返します。

設定

サーバーでは、コマンドラインフラグと環境変数を使用して、さまざまなオプションを設定できます。

コマンドラインフラグ

フラグ	デフォルト	説明
--workspace	.	Go プロジェクトのルートへの絶対パス
--gopls-path	gopls	gopls バイナリへのパス
--log-level	info	ログレベル（debug、info、warn、error）
--rpc-timeout	30s	LSP 呼び出しの RPC タイムアウト
--shutdown-timeout	5s	グレースフルシャットダウンまでのタイムアウト

環境変数

すべてのフラグは、MCP_GOPLS_ プレフィックスを付けた環境変数で設定できます。

環境変数	対応するフラグ	説明
MCP_GOPLS_WORKSPACE	--workspace	Go プロジェクトのルートへの絶対パス
MCP_GOPLS_GOPLS_PATH	--gopls-path	gopls バイナリへのパス
MCP_GOPLS_LOG_LEVEL	--log-level	ログレベル（debug、info、warn、error）
MCP_GOPLS_RPC_TIMEOUT	--rpc-timeout	LSP 呼び出しの RPC タイムアウト（例：30s、1m）
MCP_GOPLS_SHUTDOWN_TIMEOUT	--shutdown-timeout	正常終了のタイムアウト

コマンドラインフラグは環境変数より優先されます。

トラブルシューティング

• 「column is beyond end of line」 – gopls が指定された位置を特定できませんでした。ファイルが保存されていること、および位置指定が 0 始まりの行・列になっていることを確認してください。go fmt を実行し、タブとスペースの配置が gopls の想定に合っていることを確認してください。
• 「no hover information available」 – シンボルが生成ファイル、または設定されたワークスペース外のモジュールに属している可能性があります。--workspace フラグがモジュールのルートを指していること、および go list ./... が成功することを確認してください。
• 「workspace not initialized」 – サーバーの初期同期が完了していません。workspace initialized のログ行が表示されるまで待つか、古い .gopls キャッシュを削除してから mcp-gopls を再起動してください。
• run_govulncheck のバイナリが見つからない – ツールは go run golang.org/x/vuln/cmd/govulncheck@latest にフォールバックするようになりましたが、引き続きマシンに外部ネットワークへのアクセスが必要です。フォールバックがブロックされる場合は、バイナリを手動でインストールしてください。

使用例

MCP に対応した AI アシスタントでサーバーを使用する場合：

# Ask the AI to get information about the code
Can you find the definition of the `ServeStdio` function in this project?

# Ask for diagnostics
Are there any errors in my main.go file?

# Ask for information about a symbol
What does the Context.WithTimeout function do in Go?

開発

git clone https://github.com/hloiseau/mcp-gopls.git
cd mcp-gopls
go mod tidy
go test ./...
go build ./cmd/mcp-gopls

テーブル駆動テストは pkg/tools にあり、CI は .github/workflows/ci.yml を通じて実行されます。

ドキュメント

• docs/usage.md – クイックスタートとツールカタログの概要
• ワークスペースリソースは resource://workspace/overview と resource://workspace/go.mod を公開します
• プロンプト（summarize_diagnostics、refactor_plan）は、一貫性のある出力をアシスタントが生成するのに役立ちます

貢献

PR やイシューを歓迎します！

• 未解決のイシューを確認するか、バグに遭遇した場合や機能を希望する場合は新しいイシューを登録してください。
• PR を作成する前に go test ./... を実行してください。
• 大きな変更（新しいツール、プロトコルの変更）については、まず設計イシューを登録して、方針を相談してください。

すべてのコントリビューションでテストカバレッジを維持し、Go のベストプラクティスに従ってください。セットアップ手順については、開発セクションを参照してください。

前提条件

• Go 1.25 以降（go1.25.4 でテスト済み）
• gopls がインストールされていること（go install golang.org/x/tools/gopls@latest）
• 任意：govulncheck（go install golang.org/x/vuln/cmd/govulncheck@latest）
• サーバーは、子プロセスとして起動する gopls に GOTOOLCHAIN=local を強制的に設定します。別のツールチェーンが必要な場合は、mcp-gopls を起動する前に環境で GOTOOLCHAIN を設定してください。

Ollama との連携

この MCP サーバーは、MCP プロトコルに対応した任意のツールで使用できます。Ollama と連携するには：

1. Ollama が実行中であることを確認します
2. MCP サーバーは独立して実行され、標準入力／標準出力を通じて通信します
3. MCP サーバーをツールプロバイダーとして使うよう、クライアントを設定します

ライセンス

Apache License 2.0