MCP Gemini Grounding

🚀 Gemini AI MCP Server

Gemini AI MCP Serverは、Gemini APIのgrounding機能を利用して、AIによるウェブ検索と要約を提供するModel Context Protocol (MCP) サーバーです。従来の検索ツールが生の検索結果を返すのとは異なり、このサーバーはGemini AIを使って情報を統合し、引用付きの包括的な回答を提供します。

🚀 クイックスタート

Gemini AI MCP Serverを使い始めるには、まず必要な前提条件を満たし、インストールと設定を行います。設定が完了すると、Claude Code内でgoogle_searchツールを使用できます。

✨ 主な機能

• Gemini AIを使ってウェブを検索し、統合された回答を提供します。
• AIによって生成された要約を、適切な引用とソースURL付きで返します。
• OAuthとAPIキーの両方の認証方式をサポートしています。
• Claude Codeや他のMCPクライアントと互換性があります。

📦 インストール

ソースからビルド

git clone https://github.com/ml0-1337/mcp-gemini-grounding.git
cd mcp-gemini-grounding
make build

利用可能なコマンドの全リストを表示するには、以下のコマンドを実行します。

make help

グローバルにインストール

# ソースから
make install

# または直接go installを使用
go install github.com/ml0-1337/mcp-gemini-grounding/cmd/gemini-grounding@latest

📚 ドキュメント

認証

サーバーは2つの認証方法をサポートしています。

1. OAuth認証情報 (推奨)

   • ~/.gemini/oauth_creds.json の認証情報を自動的に使用します。
   • これらはGemini CLIで認証する際に作成されます。
   • 詳細な手順については、OAuth2セットアップガイド を参照してください。

2. APIキー (代替手段)

   • GEMINI_API_KEY 環境変数を設定します。
   • APIキーは Google AI Studio から取得できます。

Claude Codeの設定

必要に応じて、適切な設定スコープを選択してください。

⚠️ 重要提示

以下のCLIコマンドを使用する際には、バイナリへの完全な絶対パスを指定する必要があります (例: /Users/username/projects/mcp-gemini-grounding/mcp-gemini-grounding)。./mcp-gemini-grounding のような相対パスを使用すると、サーバーが正常に起動しません。

1. ローカルスコープ (プロジェクト固有、非公開)

最適なシナリオ: 個人開発用サーバー、実験的な設定、または機密性の高い認証情報を持つサーバー。

オプションA: CLIを使用する (推奨)

# グローバルにインストールされている場合
claude mcp add gemini-grounding

# または完全な絶対パスを指定する (必須 - 相対パスは失敗します)
claude mcp add gemini-grounding /full/path/to/mcp-gemini-grounding
# 例: claude mcp add gemini-grounding /Users/username/projects/mcp-gemini-grounding/mcp-gemini-grounding

オプションB: 手動設定

1. Claude Codeでプロジェクトを開きます。
2. 下部のステータスバーのMCPサーバーアイコンをクリックします。
3. "Add MCP Server..." を選択します。
4. "gemini" を選択し、以下のように設定します。

{
  "mcpServers": {
    "gemini-grounding": {
      "command": "/path/to/mcp-gemini-grounding",
      "env": {
        "GEMINI_API_KEY": "$GEMINI_API_KEY"
      }
    }
  }
}

この設定は、プロジェクトの .claude/settings.local.json ファイルに保存され、他の人と共有されません。

2. プロジェクトスコープ (チーム共有)

最適なシナリオ: すべてのメンバーが同じMCPサーバー設定を必要とするチームコラボレーション。

オプションA: CLIを使用する (推奨)

# グローバルにインストールされている場合
claude mcp add gemini-grounding -s project

# または完全な絶対パスを指定する (必須 - 相対パスは失敗します)
claude mcp add gemini-grounding -s project /full/path/to/mcp-gemini
# 例: claude mcp add gemini-grounding -s project /Users/username/projects/mcp-gemini-grounding/mcp-gemini-grounding

オプションB: 手動設定

1. プロジェクトルートに .mcp.json ファイルを作成します。
2. 以下の設定を追加します。

{
  "mcpServers": {
    "gemini-grounding": {
      "command": "mcp-gemini-grounding",
      "env": {
        "GEMINI_API_KEY": "$GEMINI_API_KEY"
      }
    }
  }
}

3. このファイルをバージョン管理にコミットします。
4. チームメンバーはローカルで GEMINI_API_KEY 環境変数を設定する必要があります。

⚠️ 重要提示

実際のAPIキーをコミットしないでください。常に環境変数の参照 (例: $GEMINI_API_KEY) を使用してください。

3. ユーザースコープ (グローバル)

最適なシナリオ: すべてのプロジェクトで利用可能にしたい個人用のユーティリティサーバー。

オプションA: CLIを使用する (推奨)

# グローバルにインストールされている場合
claude mcp add gemini-grounding -s user

# または完全な絶対パスを指定する (必須 - 相対パスは失敗します)
claude mcp add gemini-grounding -s user /full/path/to/mcp-gemini
# 例: claude mcp add gemini-grounding -s user /Users/username/projects/mcp-gemini-grounding/mcp-gemini-grounding

オプションB: 手動設定

1. Claude Codeの設定を開きます。
2. MCPサーバーの設定に移動します。
3. ユーザー設定にgeminiサーバーを追加します。

{
  "mcpServers": {
    "gemini-grounding": {
      "command": "gemini",
      "env": {
        "GEMINI_API_KEY": "$GEMINI_API_KEY"
      }
    }
  }
}

go install でグローバルにインストールした場合は、単に "command": "gemini" を使用できます。

環境変数の設定

サーバーを追加した後、APIキーを設定します。

# macOS/Linux
export GEMINI_API_KEY="your-api-key-here"

# Windows (PowerShell)
$env:GEMINI_API_KEY="your-api-key-here"

# Windows (Command Prompt)
set GEMINI_API_KEY=your-api-key-here

永続的な設定にするには、エクスポートをシェルプロファイル (~/.bashrc, ~/.zshrc など) に追加してください。

設定の優先順位

Claude Codeは、設定を以下の順序 (最も高い優先度から最も低い優先度) で適用します。

1. ローカルスコープ - プロジェクト固有の設定がすべてを上書きします。
2. プロジェクトスコープ - 共有されたチーム設定。
3. ユーザースコープ - グローバルな個人設定。

これにより、必要に応じて個人設定が共有設定を上書きすることができます。

セキュリティのベストプラクティス

1. APIキーの管理

   • 設定ファイルにAPIキーを直接コミットしないでください。
   • 環境変数 $GEMINI_API_KEY を使用してください。
   • シェルプロファイルに環境変数を設定します。

     export GEMINI_API_KEY="your-api-key-here"
     

2. OAuth認証情報

   • サーバーは、~/.gemini/oauth_creds.json のOAuth認証情報が利用可能な場合、自動的に使用します。
   • OAuthについては設定が必要ありません - 自動的に検出されます。

3. チーム環境

   • 機密データを含まないプロジェクトスコープ (.mcp.json) を使用してください。
   • 各チームメンバーはローカルで自分のAPIキーを設定します。
   • セキュリティ向上のためにOAuthを検討してください。

💻 使用例

基本的な使用法

設定が完了すると、Claude Code内で google_search ツールが利用可能になります。Claudeに検索と情報の要約を依頼することで使用できます。

• "Search for the latest news about AI"
• "Find information about quantum computing"
• "What are the current trends in web development?"

ツールのスキーマ

{
  "name": "google_search",
  "description": "Uses Google Search via Gemini AI grounding to find information and provide synthesized answers with citations. Returns AI-generated summaries rather than raw search results.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The search query to find information on the web"
      }
    },
    "required": ["query"]
  }
}

出力形式

ツールは、以下の形式で検索結果を返します。

• インライン引用付きのメインコンテンツ (例: [1], [2])
• タイトルとURL付きのソースのリスト
• 読みやすい適切なフォーマット

出力例:

Web search results for "quantum computing":

Quantum computing is a rapidly evolving field[1]. Recent breakthroughs have shown promise for practical applications[2].

Sources:
[1] Quantum Computing Explained - MIT (https://mit.edu/quantum)
[2] Latest Quantum Breakthroughs - Nature (https://nature.com/quantum)

🔧 技術詳細

クイックスタート

# 依存関係のインストール
make deps

# プロジェクトのビルド
make build

# テストの実行
make test

# すべての品質チェックの実行
make audit

利用可能なMakeコマンド

make help を実行すると、すべての利用可能なコマンドを確認できます。主要なコマンドは以下の通りです。

• ビルドと実行: make build, make run, make install
• テスト: make test, make cover, make test-race
• 品質: make fmt, make vet, make lint, make audit
• 開発: make dev, make watch (air が必要)
• クロスプラットフォーム: make build-all (Linux、macOS、Windows用にビルド)
• MCP統合: make mcp-install, make mcp-config
• リリース: make release, make checksum

テストの実行

# すべてのテストを実行
make test

# カバレッジ付きでテストを実行
make cover

# 競合検出付きでテストを実行
make test-race

# HTMLカバレッジレポートを生成
make cover-html

テストスクリプト

OAuth2とAPIテスト用の様々なテストスクリプトが scripts/test/ ディレクトリにあります。詳細については、scripts/test/README.md を参照してください。

アーキテクチャ

graph TD
    subgraph User
        A[MCP Client e.g. Claude Code]
    end

    subgraph "mcp-gemini-grounding"
        B[cmd/gemini-grounding/main.go]
        C[internal/search]
        D[internal/gemini]
        E[internal/auth]
    end

    subgraph "Google Cloud"
        F[Gemini API]
    end

    A -- MCP Request --> B
    B -- Initializes --> C
    B -- Initializes --> D
    B -- Initializes --> E
    C -- Uses --> D
    D -- Uses --> E
    D -- Makes API Calls --> F

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style F fill:#bbf,stroke:#333,stroke-width:2px

プロジェクト構造

mcp-gemini-grounding/
├── cmd/gemini-grounding/ # Main application entry point
├── internal/
│   ├── auth/           # Authentication handling
│   ├── gemini/         # Gemini API client
│   └── search/         # MCP tool handler
├── go.mod
├── go.sum
└── README.md

トラブルシューティング

認証エラー

1. OAuth認証情報が存在することを確認します。

ls ~/.gemini/oauth_creds.json

2. またはAPIキーが設定されていることを確認します。

echo $GEMINI_API_KEY

接続問題

• インターネット接続があることを確認してください。
• あなたの地域でGemini APIにアクセスできることを確認してください。
• APIキーまたはOAuth認証情報が有効であることを確認してください。

結果が得られない場合

• 異なる検索クエリを試してみてください。
• Gemini APIのステータスを確認してください。
• レート制限を超えていないことを確認してください。

📄 ライセンス

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

コントリビューション

コントリビューションは大歓迎です！プルリクエストを送信してください。

リポジトリ

https://github.com/ml0-1337/mcp-gemini-grounding