Gopls MCP

🚀 gopls-mcp

このプロジェクトは、gopls（Go言語サーバー）をClaude Code、Claude Desktop、VS CodeなどのMCP互換ホストと統合するModel Context Protocol (MCP) サーバーです。Claude Code と共同開発し、MCPプロトコルを通じてシームレスなGo言語サーバー機能を提供し、AI駆動のコーディング環境で強力なGo開発支援を実現します。

🚀 クイックスタート

前提条件

• 有効な go.mod ファイルを持つGoワークスペース
• Docker（推奨）またはGo 1.24以上がインストールされていること

手順

1. Goプロジェクトをクローンまたはダウンロード
2. gopls-mcpサーバーを起動

   docker run -d -v $(pwd):/workspace -p 8080:8080 megagrindstone/gopls-mcp:latest
   

3. Claude Codeと統合

   claude mcp add --transport http gopls-mcp http://localhost:8080
   

4. 統合をテスト - Claude CodeにGoコードの支援を依頼してみましょう！

✨ 主な機能

このMCPサーバーは、6つのカテゴリに分かれた14の包括的なGo開発ツールを提供し、完全なマルチワークスペースサポートを備えています。

🏢 ワークスペース管理ツール (1)

• 📋 ワークスペースの一覧表示 - 構成されたすべてのGoワークスペースを検出して列挙します。

🎯 コアナビゲーションツール (3)

• 🎯 定義へ移動 - Goワークスペース全体でシンボルの定義に移動します。
• 🔍 参照の検索 - 関数、変数、型のすべての参照を見つけます。
• 📖 ホバー情報 - ドキュメント、型情報、シグネチャを取得します。

🔍 診断と分析ツール (3)

• 🚨 診断情報の取得 - Goファイルのコンパイルエラー、警告、診断情報を取得します。
• 📄 ドキュメントシンボル - Goファイルで定義されたシンボル（関数、型など）のアウトラインを取得します。
• 🔎 ワークスペースシンボル - 全体のGoワークスペース/プロジェクトでシンボルを検索します。

💡 コード支援ツール (2)

• ✍️ シグネチャヘルプ - 関数のシグネチャヘルプとパラメータ情報を取得します。
• 🤖 コード補完 - インテリジェントなコード補完提案を取得します。

🧭 高度なナビゲーションツール (2)

• 🏷️ 型定義 - シンボルの型定義に移動します。
• 🔗 実装の検索 - インターフェースまたはメソッドのすべての実装を見つけます。

🛠️ コードメンテナンスツール (3)

• ✨ ドキュメントの整形 - gofmt標準に従ってGoソースファイルを整形します。
• 📦 インポートの整理 - インポート文を整理してクリーンアップします。
• 💭 インレイヒント - 暗黙的なパラメータ名と型情報のインレイヒントを取得します。

すべてのツールは既存のGoワークスペースで動作し、複数のワークスペースを同時にサポートし、正確で高速な結果を得るためにgoplsを活用します。

📦 インストール

Claude Codeとの統合（推奨）

gopls-mcpを使用する最も簡単な方法は、Streamable HTTPトランスポートを使用してClaude Codeと統合することです。

1. Goワークスペースでサーバーを起動

   # Dockerを使用した単一ワークスペース（推奨）
   docker run -d -v /path/to/your/go/project:/workspace -p 8080:8080 megagrindstone/gopls-mcp:latest
   
   # Dockerを使用した複数ワークスペース
   docker run -d \
     -v /path/to/project1:/workspace1 \
     -v /path/to/project2:/workspace2 \
     -v /path/to/project3:/workspace3 \
     -p 8080:8080 \
     megagrindstone/gopls-mcp:latest -workspace /workspace1,/workspace2,/workspace3
   
   # ソースからビルド（単一ワークスペース）
   go build -o gopls-mcp
   ./gopls-mcp -workspace /path/to/your/go/project
   
   # ソースからの複数ワークスペース
   ./gopls-mcp -workspace /path/to/project1,/path/to/project2,/path/to/project3
   

2. Claude Codeに追加

   claude mcp add --transport http gopls-mcp http://localhost:8080
   

3. 使用開始 - Claude Codeの会話でGoツールが利用可能になります！

Claude Desktopとの統合

Claude Desktopの場合、MCP設定に以下を追加します。

単一ワークスペース

{
  "mcpServers": {
    "gopls-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/go/project:/workspace",
        "-p", "8080:8080",
        "megagrindstone/gopls-mcp:latest"
      ]
    }
  }
}

複数ワークスペース

{
  "mcpServers": {
    "gopls-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/project1:/workspace1",
        "-v", "/path/to/project2:/workspace2",
        "-v", "/path/to/project3:/workspace3",
        "-p", "8080:8080",
        "megagrindstone/gopls-mcp:latest",
        "-workspace", "/workspace1,/workspace2,/workspace3"
      ]
    }
  }
}

その他のMCPホスト

VS Codeやその他のMCPホストの場合、Streamable HTTPトランスポートを使用します。

{
  "servers": {
    "gopls-mcp": {
      "type": "http",
      "url": "http://localhost:8080"
    }
  }
}

💻 使用例

統合後、会話の中で自然にこれらのツールを使用できます。マルチワークスペースサポートにより、複数のGoプロジェクトを同時に操作できます。

ワークスペース管理

"利用可能なワークスペースはどれですか？"
"構成されたすべてのGoプロジェクトをリストしてください"

コアナビゲーションツール

"project1で`ProcessRequest`関数はどこで定義されていますか？"
"すべてのワークスペースで`UserService`が使用されているすべての場所を表示してください"
"`http.Client`構造体には何が含まれていますか？"

診断と分析ツール

"main.goにコンパイルエラーはありますか？"
"client.goで定義されたすべての関数と型を表示してください"
"ワークスペース全体で'Handler'という名前のすべてのシンボルを見つけてください"

コード支援ツール

"`log.Printf`関数はどのようなパラメータを取りますか？"
"この位置のコード補完提案を表示してください"

高度なナビゲーションツール

"この変数の型定義は何ですか？"
"Writerインターフェースのすべての実装を見つけてください"

コードメンテナンスツール

"このGoファイルをgofmt標準に従って整形してください"
"このファイルのインポートを整理してクリーンアップしてください"
"このコード範囲の型ヒントを表示してください"

MCPサーバーは、リクエストに基づいて適切なツールを自動的に使用し、Goワークスペースから正確な情報を提供します。すべてのツールは、複数のプロジェクトで作業する際にワークスペース固有の操作をサポートします。

📚 ドキュメント

サーバーオプション

• -workspace（必須）: Goワークスペースディレクトリのパス

  • 単一ワークスペース: -workspace /path/to/project
  • 複数ワークスペース: -workspace /project1,/project2,/project3
  • パスにスペースを含む場合: -workspace "/path with spaces/project1,/project2"

  ⚠️ メモリ使用量に関する注意: 各ワークスペースは専用のgoplsプロセスを実行するため、約300MBのRAMを使用します。複数のワークスペースを使用する場合は、適切に計画してください。

  • 1つのワークスペース: ~300MB RAM
  • 5つのワークスペース: ~1.5GB RAM
  • 10つのワークスペース: ~3GB RAM

• -transport（オプション）: トランスポートタイプ ('http'または'stdio'を受け付け、デフォルトは'http')

• ポート: 8080に固定（Streamable HTTPトランスポートのみ）

トランスポートオプション

Streamable HTTPトランスポート（デフォルト）

# Streamable HTTPトランスポートを使用した単一ワークスペース（デフォルト）
./gopls-mcp -workspace /path/to/go/project
./gopls-mcp -workspace /path/to/go/project -transport http

# Streamable HTTPトランスポートを使用した複数ワークスペース
./gopls-mcp -workspace /project1,/project2,/project3
./gopls-mcp -workspace /project1,/project2 -transport http

# Dockerを使用した単一ワークスペース（Streamable HTTPトランスポート）
docker run -v /path/to/go/project:/workspace -p 8080:8080 megagrindstone/gopls-mcp:latest

# Dockerを使用した複数ワークスペース（Streamable HTTPトランスポート）
docker run \
  -v /project1:/workspace1 \
  -v /project2:/workspace2 \
  -v /project3:/workspace3 \
  -p 8080:8080 \
  megagrindstone/gopls-mcp:latest -workspace /workspace1,/workspace2,/workspace3

Stdioトランスポート

# Stdioトランスポートを使用した単一ワークスペース
./gopls-mcp -workspace /path/to/go/project -transport stdio

# Stdioトランスポートを使用した複数ワークスペース
./gopls-mcp -workspace /project1,/project2,/project3 -transport stdio

# Dockerを使用した単一ワークスペース（stdioトランスポート）
docker run -i -v /path/to/go/project:/workspace megagrindstone/gopls-mcp:latest -transport stdio

# Dockerを使用した複数ワークスペース（stdioトランスポート）
docker run -i \
  -v /project1:/workspace1 \
  -v /project2:/workspace2 \
  -v /project3:/workspace3 \
  megagrindstone/gopls-mcp:latest -workspace /workspace1,/workspace2,/workspace3 -transport stdio

Stdioトランスポートを使用するClaude Desktopの場合:

{
  "mcpServers": {
    "gopls-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/go/project:/workspace",
        "megagrindstone/gopls-mcp:latest",
        "-transport", "stdio"
      ]
    }
  }
}

ロギング設定

サーバーは、環境変数を介して構成可能なレベルと形式で構造化ロギングをサポートしています。

環境変数

• LOG_LEVEL: ロギングレベルを設定（DEBUG、INFO、WARN、ERROR） - デフォルトはINFO
• LOG_FORMAT: ログ出力形式を設定（text、json） - デフォルトはtext

使用例

# カスタムロギングを使用したネイティブ実行
LOG_LEVEL=DEBUG ./gopls-mcp -workspace /path/to/go/project
LOG_FORMAT=json LOG_LEVEL=WARN ./gopls-mcp -workspace /path/to/go/project

# ロギング設定を使用したDocker実行
docker run -e LOG_LEVEL=DEBUG -v /path/to/go/project:/workspace -p 8080:8080 megagrindstone/gopls-mcp:latest
docker run -e LOG_FORMAT=json -e LOG_LEVEL=INFO -v /path/to/go/project:/workspace -p 8080:8080 megagrindstone/gopls-mcp:latest

ワークスペース要件

Goワークスペースには以下が含まれている必要があります。

• 有効な go.mod ファイル
• 適切なGoモジュール構造
• アクセス可能なGoソースファイル

サーバーは自動的にワークスペースでgoplsを初期化し、セッション全体で言語サーバーの接続を維持します。

🔧 技術詳細

Dockerデプロイメント

Docker Hubイメージの使用

Docker Hubにはマルチプラットフォームサポートを持つ事前構築済みのDockerイメージを管理しています。

# 最新の安定リリース
docker pull megagrindstone/gopls-mcp:latest

# 特定のバージョン
docker pull megagrindstone/gopls-mcp:v0.3.0

# 単一のGoプロジェクトで実行
docker run -v /path/to/go/project:/workspace -p 8080:8080 megagrindstone/gopls-mcp:latest

# 複数のGoプロジェクトで実行
docker run \
  -v /path/to/project1:/workspace1 \
  -v /path/to/project2:/workspace2 \
  -v /path/to/project3:/workspace3 \
  -p 8080:8080 \
  megagrindstone/gopls-mcp:latest -workspace /workspace1,/workspace2,/workspace3

利用可能なタグ

• latest - 最新の安定リリース
• v* - セマンティックバージョンタグ（例: v0.3.0）
• main - 最新の開発ビルド

マルチプラットフォームサポート

Dockerイメージは以下をサポートしています。

• linux/amd64 - Intel/AMD 64ビット
• linux/arm64 - ARM 64ビット（Apple Silicon、ARMサーバー）

開発セットアップ

前提条件

• Go 1.24以上
• Docker（オプション）
• golangci-lint（オプション、リンティング用）

ソースからのビルド

# リポジトリをクローン
git clone https://github.com/MegaGrindStone/gopls-mcp.git
cd gopls-mcp

# バイナリをビルド
go build -o gopls-mcp

# 単一のGoワークスペースで実行
./gopls-mcp -workspace /path/to/your/go/project

# 複数のGoワークスペースで実行
./gopls-mcp -workspace /path/to/project1,/path/to/project2,/path/to/project3

テスト

# 詳細出力でテストを実行
go test ./... -v -count=1 -p 1

# リンターを実行
golangci-lint run ./...

# コードを整形
go fmt ./...

Docker開発

# Dockerイメージをビルド
docker build -t gopls-mcp .

# 単一ワークスペースでローカルテスト
docker run -v /path/to/test/project:/workspace -p 8080:8080 gopls-mcp

# 複数ワークスペースでローカルテスト
docker run \
  -v /path/to/test/project1:/workspace1 \
  -v /path/to/test/project2:/workspace2 \
  -p 8080:8080 \
  gopls-mcp -workspace /workspace1,/workspace2

📄 APIドキュメント

MCPツール

すべてのツールは、操作対象のワークスペースを指定するためのworkspaceパラメータが必要です。ワークスペース内の相対パスを使用します。

🏢 ワークスペース管理ツール

list_workspaces

サーバーに構成されたすべての利用可能なGoワークスペースをリストします。

パラメータ: なし

例:

{
  "name": "list_workspaces",
  "arguments": {}
}

🎯 コアナビゲーションツール

go_to_definition

Goワークスペース内のシンボル定義に移動します。

パラメータ:

• workspace (string): このリクエストで使用するワークスペースパス
• path (string): Goファイルの相対パス（例: main.go, pkg/client.go）
• line (number): 行番号（1から始まる）
• character (number): 文字位置（0から始まる）

例:

{
  "name": "go_to_definition",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "main.go",
    "line": 10,
    "character": 5
  }
}

find_references

Goワークスペース全体でシンボルのすべての参照を見つけます。

パラメータ:

• workspace (string): このリクエストで使用するワークスペースパス
• path (string): Goファイルの相対パス
• line (number): 行番号（1から始まる）
• character (number): 文字位置（0から始まる）
• includeDeclaration (boolean): 結果に宣言を含めるかどうか

例:

{
  "name": "find_references",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "pkg/client.go",
    "line": 10,
    "character": 5,
    "includeDeclaration": true
  }
}

get_hover_info

シンボルのドキュメントと型情報を取得します。

パラメータ:

• workspace (string): このリクエストで使用するワークスペースパス
• path (string): Goファイルの相対パス
• line (number): 行番号（1から始まる）
• character (number): 文字位置（0から始まる）

例:

{
  "name": "get_hover_info",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "mcp.go",
    "line": 10,
    "character": 5
  }
}

🔍 診断と分析ツール

get_diagnostics

Goファイルのコンパイルエラー、警告、診断情報を取得します。

パラメータ:

• workspace (string): このリクエストで使用するワークスペースパス
• path (string): Goファイルの相対パス

例:

{
  "name": "get_diagnostics",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "main.go"
  }
}

get_document_symbols

Goファイルで定義されたシンボル（関数、型など）のアウトラインを取得します。

パラメータ:

• workspace (string): このリクエストで使用するワークスペースパス
• path (string): Goファイルの相対パス

例:

{
  "name": "get_document_symbols",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "client.go"
  }
}

get_workspace_symbols

全体のGoワークスペース/プロジェクトでシンボルを検索します。

パラメータ:

• workspace (string): このリクエストで使用するワークスペースパス
• query (string): 検索するシンボル名

例:

{
  "name": "get_workspace_symbols",
  "arguments": {
    "workspace": "/path/to/workspace",
    "query": "Client"
  }
}

💡 コード支援ツール

get_signature_help

指定された位置の関数シグネチャヘルプ（パラメータ情報）を取得します。

パラメータ:

• workspace (string): このリクエストで使用するワークスペースパス
• path (string): Goファイルの相対パス
• line (number): 行番号（1から始まる）
• character (number): 文字位置（0から始まる）

例:

{
  "name": "get_signature_help",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "main.go",
    "line": 15,
    "character": 20
  }
}

get_completions

指定された位置のコード補完提案を取得します。

パラメータ:

• workspace (string): このリクエストで使用するワークスペースパス
• path (string): Goファイルの相対パス
• line (number): 行番号（1から始まる）
• character (number): 文字位置（0から始まる）

例:

{
  "name": "get_completions",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "main.go",
    "line": 8,
    "character": 5
  }
}

🧭 高度なナビゲーションツール

get_type_definition

指定された位置のシンボルの型定義に移動します。

パラメータ:

• workspace (string): このリクエストで使用するワークスペースパス
• path (string): Goファイルの相対パス
• line (number): 行番号（1から始まる）
• character (number): 文字位置（0から始まる）

例:

{
  "name": "get_type_definition",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "client.go",
    "line": 25,
    "character": 10
  }
}

find_implementations

指定された位置のインターフェースまたはメソッドのすべての実装を見つけます。

パラメータ:

• workspace (string): このリクエストで使用するワークスペースパス
• path (string): Goファイルの相対パス
• line (number): 行番号（1から始まる）
• character (number): 文字位置（0から始まる）

例:

{
  "name": "find_implementations",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "interfaces.go",
    "line": 12,
    "character": 8
  }
}

🛠️ コードメンテナンスツール

format_document

gofmt標準に従ってGoソースファイルを整形します。

パラメータ:

• workspace (string): このリクエストで使用するワークスペースパス
• path (string): Goファイルの相対パス

例:

{
  "name": "format_document",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "main.go"
  }
}

organize_imports

Goファイルのインポート文を整理してクリーンアップします。

パラメータ:

• workspace (string): このリクエストで使用するワークスペースパス
• path (string): Goファイルの相対パス

例:

{
  "name": "organize_imports",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "client.go"
  }
}

get_inlay_hints

Goファイル内の範囲に対するインレイヒント（暗黙的なパラメータ名、型情報）を取得します。

パラメータ:

• workspace (string): このリクエストで使用するワークスペースパス
• path (string): Goファイルの相対パス
• startLine (number): 開始行番号（1から始まる）
• startChar (number): 開始文字位置（0から始まる）
• endLine (number): 終了行番号（1から始まる）
• endChar (number): 終了文字位置（0から始まる）

例:

{
  "name": "get_inlay_hints",
  "arguments": {
    "workspace": "/path/to/workspace",
    "path": "main.go",
    "startLine": 10,
    "startChar": 0,
    "endLine": 20,
    "endChar": 50
  }
}

トラブルシューティング

一般的な問題

"workspace flag is required"

• サーバーを実行する際に -workspace フラグを指定していることを確認してください。
• ワークスペースパスには有効なGoモジュールが含まれている必要があります。

"Failed to start gopls"

• goplsがPATHに含まれていることを確認してください（Dockerでは自動的に処理されます）。
• Goワークスペースに有効な go.mod ファイルがあることを確認してください。
• ワークスペースパスがアクセス可能であることを確認してください。

"Connection refused"

• サーバーがポート8080で実行されていることを確認してください。
• 他のサービスがこのポートを使用していないことを確認してください。
• MCPサーバーが http://localhost:8080 でアクセス可能であることを確認してください。

デバッグモード

問題をデバッグするには、詳細なロギングでサーバーを実行します。

# デバッグロギングを使用したネイティブ実行
LOG_LEVEL=DEBUG ./gopls-mcp -workspace /path/to/project

# デバッグロギングを使用したDocker実行（Streamable HTTP）
docker run -e LOG_LEVEL=DEBUG -v /path/to/project:/workspace -p 8080:8080 megagrindstone/gopls-mcp:latest

# Dockerコンテナのログを表示
docker logs <container-id>

# 解析しやすいJSON形式のロギング
docker run -e LOG_FORMAT=json -e LOG_LEVEL=DEBUG -v /path/to/project:/workspace -p 8080:8080 megagrindstone/gopls-mcp:latest

コントリビューション

gopls-mcpの改善に向けたコントリビューションを歓迎します！このプロジェクトはClaude Codeと共同開発されており、コミュニティがさらに改善することを期待しています。

開発プロセス

1. リポジトリをフォーク
2. 機能ブランチを作成
3. 変更を加える
4. 新機能に対するテストを追加
5. テストスイートを実行: go test ./... -v -count=1 -p 1
6. リンターを実行: golangci-lint run ./...
7. プルリクエストを送信

コードスタイル

• 標準的なGoの規約に従ってください。
• go fmt を使用してコードを整形してください。
• 既存のコードベースのパターンに従ってください。
• 新機能に対するテストを追加してください。

問題の報告

GitHubの問題トラッカー で以下の情報を含めて問題を報告してください。

• 使用しているオペレーティングシステムとGoのバージョン
• 問題を再現する手順
• 期待される動作と実際の動作
• 関連するログまたはエラーメッセージ

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細については LICENSE ファイルを参照してください。

謝辞

• Claude Code - このプロジェクトはClaude Code、AnthropicのAI駆動のコーディングアシスタントと共同開発されました。
• goplsチーム - 優れたGo言語サーバーを作成してくれたチームに感謝します。
• Model Context Protocol - この統合を可能にするフレームワークを提供してくれたチームに感謝します。
• Goコミュニティ - このプロジェクトを可能にするツールとエコシステムを構築してくれたコミュニティに感謝します。

---

作者: Gerard Adam
協力: Claude Codeと共同開発
リポジトリ: https://github.com/MegaGrindStone/gopls-mcp
Docker Hub: https://hub.docker.com/r/megagrindstone/gopls-mcp