Google Research MCP

🚀 Google Researcher MCP Server

AIアシスタント向けの専門的な調査ツールです。Google検索、ウェブスクレイピング、学術論文、特許などをサポートします。

🚀 クイックスタート

Claude Desktop (macOS)

~/Library/Application Support/Claude/claude_desktop_config.jsonに以下を追加します。

{
  "mcpServers": {
    "google-researcher": {
      "command": "npx",
      "args": ["-y", "google-researcher-mcp"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "YOUR_API_KEY_HERE",
        "GOOGLE_CUSTOM_SEARCH_ID": "YOUR_SEARCH_ID_HERE"
      }
    }
  }
}

Claude Desktop (Windows)

%APPDATA%\Claude\claude_desktop_config.jsonに以下を追加します。

{
  "mcpServers": {
    "google-researcher": {
      "command": "npx",
      "args": ["-y", "google-researcher-mcp"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "YOUR_API_KEY_HERE",
        "GOOGLE_CUSTOM_SEARCH_ID": "YOUR_SEARCH_ID_HERE"
      }
    }
  }
}

ワンクリックインストール (MCPB)

GitHub Releasesから最新の.mcpbバンドルをダウンロードし、Claude Desktopでダブルクリックしてインストールします。Google APIの資格情報の入力を求められます。

Claude Code

~/.claude.jsonに以下を追加します。

{
  "mcpServers": {
    "google-researcher": {
      "command": "npx",
      "args": ["-y", "google-researcher-mcp"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "YOUR_API_KEY_HERE",
        "GOOGLE_CUSTOM_SEARCH_ID": "YOUR_SEARCH_ID_HERE"
      }
    }
  }
}

Cline / Roo Code

MCP設定で上記のJSON設定を使用します。

APIキーが必要ですか？ APIセットアップガイドを参照して、Google APIの資格情報を取得する手順を確認してください。

ローカル開発

git clone https://github.com/zoharbabin/google-researcher-mcp.git && cd google-researcher-mcp
npm install && npx playwright install chromium
cp .env.example .env   # 次に.envにGoogle APIキーを追加します
npm run dev            # サーバーがSTDIOトランスポートで起動します

注意: これはSTDIOモードでサーバーを起動します。ローカルのAIアシスタント統合にはこれで十分です。ウェブベースまたはマルチクライアントの設定では、OAuthを使用したHTTPトランスポートが必要です。トランスポートの選択を参照してください。

動作確認

設定が完了したら、AIアシスタントに以下のように問いかけます。

"AI規制に関する最新のニュースを検索して"

アシスタントはgoogle_news_searchツールを使用して、現在の記事を返します。検索結果が表示されれば、サーバーは正常に動作しています。

✨ 主な機能

コア機能

MCPプロトコルサポート

本番環境対応

詳細なドキュメントはこちら: YouTubeトランスクリプト · アーキテクチャ · テスト

📦 インストール

前提条件

• Node.js 20.0.0以上
• Google APIキー:
  • カスタム検索APIキー
  • カスタム検索エンジンID
• Chromium (JavaScriptレンダリング用): npx playwright install chromium で自動的にインストールされます
• OAuth 2.1プロバイダー (HTTPトランスポートのみ): JWTを発行する外部認証サーバー (例: Auth0、Okta)。STDIOでは不要です。

インストールとセットアップ

1. リポジトリをクローンします:

   git clone https://github.com/zoharbabin/google-researcher-mcp.git
   cd google-researcher-mcp
   

2. 依存関係をインストールします:

   npm install
   npx playwright install chromium
   

3. 環境変数を設定します:

   cp .env.example .env
   

   .env を開き、Google APIキーを追加します。他の変数はすべてオプションです。.env.example のコメントを参照して詳細な説明を確認してください。

サーバーの起動

• 開発環境 (ファイル変更時に自動リロード):

  npm run dev
  

• 本番環境:

  npm run build
  npm start
  

Dockerでの実行

# イメージをビルドします
docker build -t google-researcher-mcp .

# STDIOモードで実行します (デフォルト、MCPクライアント用)
docker run -i --rm --env-file .env google-researcher-mcp

# ポート3000でHTTPトランスポートを使用して実行します
# (MCP_TEST_MODE= はDockerfileのデフォルトの "stdio" を上書きしてHTTPを有効にします)
docker run -d --rm --env-file .env -e MCP_TEST_MODE= -p 3000:3000 google-researcher-mcp

Docker Compose (クイックなHTTPトランスポートセットアップ):

cp .env.example .env   # APIキーを入力します
docker compose up --build
curl http://localhost:3000/health

Claude CodeでのDocker使用 (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "google-researcher": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file", "/path/to/.env", "google-researcher-mcp"]
    }
  }
}

セキュリティに関する注意: シークレットをDockerイメージにベイクしないでください。常に --env-file または -e フラグを使用してランタイムで渡してください。

💻 使用例

トランスポートの選択

推奨事項: ローカルのAIアシスタント統合には STDIO を使用します。共有サービスまたはウェブアプリケーション統合が必要な場合は、HTTP+SSE を使用します。

クライアント統合

STDIOクライアント (ローカルプロセス)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["dist/server.js"]
});
const client = new Client({ name: "my-client" });
await client.connect(transport);

// Googleを検索します
const searchResult = await client.callTool({
  name: "google_search",
  arguments: { query: "Model Context Protocol" }
});
console.log(searchResult.content[0].text);

// YouTubeトランスクリプトを抽出します
const transcript = await client.callTool({
  name: "scrape_page",
  arguments: { url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }
});
console.log(transcript.content[0].text);

HTTP+SSEクライアント (ウェブアプリケーション)

構成された認証サーバーから有効なOAuth 2.1ベアラートークンが必要です。

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("http://localhost:3000/mcp"),
  {
    getAuthorization: async () => `Bearer YOUR_ACCESS_TOKEN`
  }
);
const client = new Client({ name: "my-client" });
await client.connect(transport);

const result = await client.callTool({
  name: "search_and_scrape",
  arguments: { query: "Model Context Protocol", num_results: 3 }
});
console.log(result.content[0].text);

管理API

管理およびモニタリングエンドポイント (HTTPトランスポートのみ):

🔧 技術詳細

システムアーキテクチャ

graph TD
    A[MCP Client] -->|local process| B[STDIO Transport]
    A -->|network| C[HTTP+SSE Transport]

    C --> L[OAuth 2.1 + Rate Limiter]
    L --> D
    C -.->|session replay| K[Event Store]
    B --> D[McpServer<br>MCP SDK routing + dispatch]

    D --> F[google_search]
    D --> G[scrape_page]
    D --> I[search_and_scrape]
    D --> IMG[google_image_search]
    D --> NEWS[google_news_search]
    I -.->|delegates| F
    I -.->|delegates| G
    I --> Q[Quality Scoring]

    G --> N[SSRF Validator]
    N --> S1[CheerioCrawler<br>static HTML]
    S1 -.->|insufficient content| S2[Playwright<br>JS rendering]
    G --> YT[YouTube Transcript<br>Extractor]

    F & G & IMG & NEWS --> J[Persistent Cache<br>memory + disk]

    D -.-> R[MCP Resources]
    D -.-> P[MCP Prompts]

    style J fill:#f9f,stroke:#333,stroke-width:2px
    style K fill:#ccf,stroke:#333,stroke-width:2px
    style L fill:#f99,stroke:#333,stroke-width:2px
    style N fill:#ff9,stroke:#333,stroke-width:2px
    style Q fill:#9f9,stroke:#333,stroke-width:2px

詳細な説明は、アーキテクチャガイドを参照してください。

📚 詳細ドキュメント

AIアシスタント (LLM) 向け

このドキュメントを読んでいるAIアシスタントの方へ、このMCPサーバーの使用方法は以下の通りです。

推奨ツール選択

ツール呼び出しの例

// トピックを調査する (ほとんどのクエリに推奨)
{ "name": "search_and_scrape", "arguments": { "query": "climate change effects 2024", "num_results": 5 } }

// 追跡付きの多段階調査 (複雑な調査用)
{ "name": "sequential_search", "arguments": { "searchStep": "Starting research on quantum computing", "stepNumber": 1, "totalStepsEstimate": 4, "nextStepNeeded": true } }

// 学術論文を検索する (引用付きの査読済みソース)
{ "name": "academic_search", "arguments": { "query": "transformer neural networks", "num_results": 5 } }

// 特許を検索する (先行技術、FTO分析)
{ "name": "patent_search", "arguments": { "query": "machine learning optimization", "search_type": "prior_art" } }

// 最新のニュースを取得する
{ "name": "google_news_search", "arguments": { "query": "AI regulations", "freshness": "week" } }

// 画像を検索する
{ "name": "google_image_search", "arguments": { "query": "solar panel installation", "type": "photo" } }

// 特定のページを読む
{ "name": "scrape_page", "arguments": { "url": "https://example.com/article" } }

// YouTubeトランスクリプトを取得する
{ "name": "scrape_page", "arguments": { "url": "https://www.youtube.com/watch?v=VIDEO_ID" } }

主要な動作

• キャッシュ: 検索結果は30分、スクレイピング結果は1時間キャッシュされます。繰り返しのクエリは高速です。
• 品質スコアリング: search_and_scrape はソースを関連性、新鮮さ、信頼性、コンテンツ品質でランク付けします。
• グレースフルフェイル: 一部のソースが失敗しても、成功したソースからの結果が返されます。
• ドキュメントサポート: scrape_page はPDF、DOCX、PPTXを自動検出してテキストを抽出します。

利用可能なツール

各ツールの使用時期

ツールリファレンス

search_and_scrape (調査に推奨)

Googleを検索し、トップの結果からコンテンツを1回の呼び出しで取得します。品質スコア付けされた重複排除されたテキストをソースの属性付きで返します。応答にサイズメタデータ (estimatedTokens、sizeCategory、truncated) が含まれます。

google_search

Googleからランク付けされたURLを返します。リンクのみが必要で、コンテンツは不要な場合に使用します。

google_image_search

フィルタリングオプション付きでGoogle画像を検索します。

google_news_search

新鮮さと日付のソート付きでGoogleニュースを検索します。

scrape_page

任意のURLからテキストを抽出します。ウェブページ (静的/JS)、YouTube (トランスクリプト)、ドキュメント (PDF/DOCX/PPTX) を自動検出します。

sequential_search

多段階調査の状態を追跡します。sequential_thinking パターンに従います: あなたが推論し、ツールが状態を追跡します。

academic_search

Googleカスタム検索APIを介して学術論文を検索し、学術ソース (arXiv、PubMed、IEEE、Nature、Springerなど) にフィルタリングします。事前にフォーマットされた引用付きの論文を返します。

patent_search

Google Patentsを検索して、先行技術、実施権解析 (FTO)、特許ランドスケーピングを行います。特許番号、権利者、発明者、PDFリンク付きの特許を返します。

MCPリソース

サーバーは MCPリソースプロトコル を介して状態を公開します。resources/list を使用して利用可能なリソースを発見し、resources/read を使用してそれらを取得します。

例 (MCP SDKを使用):

const resources = await client.listResources();
const recentSearches = await client.readResource({ uri: "search://recent" });

MCPプロンプト

事前構築された調査ワークフローテンプレートは MCPプロンプトプロトコル を介して利用可能です。prompts/list を使用してプロンプトを発見し、prompts/get を使用して引数付きのプロンプトを取得します。

基本的な調査プロンプト

高度な調査プロンプト

technical-deep-dive の焦点領域: architecture、implementation、comparison、best-practices、troubleshooting

例 (MCP SDKを使用):

const prompts = await client.listPrompts();

// 基本的な調査
const research = await client.getPrompt({
  name: "comprehensive-research",
  arguments: { topic: "quantum computing", depth: "standard" }
});

// 高度な調査: 特許分析
const patents = await client.getPrompt({
  name: "patent-portfolio-analysis",
  arguments: { company: "Kaltura", includeSubsidiaries: true }
});

// 高度な調査: 競争分析
const comparison = await client.getPrompt({
  name: "competitive-analysis",
  arguments: { entities: "React, Vue, Angular", aspects: "performance, learning curve, ecosystem" }
});

テスト

すべてのNPMスクリプト:

テストの哲学と構造については、テストガイド を参照してください。

開発ツール

MCPインスペクター

MCPインスペクター はMCPサーバーの視覚的なデバッグツールです。ツールを対話的にテストし、リソースを閲覧し、プロンプトを検証するために使用します。

インスペクターを実行する:

npm run inspect

これにより、http://localhost:5173 でブラウザインターフェースが開き、STDIOを介してサーバーに接続されます。

期待される内容:

インスペクターの問題のトラブルシューティング:

• "Cannot find module" エラー: まず npm run build を実行してください。インスペクターはコンパイルされたJavaScriptを必要とします。
• ツール呼び出しがAPIエラーで失敗する: .env ファイルに GOOGLE_CUSTOM_SEARCH_API_KEY と GOOGLE_CUSTOM_SEARCH_ID が設定されていることを確認してください。
• ポート5173が使用中: インスペクターUIはポート5173で実行されます。そのポートを使用している他のサービスを停止するか、別のインスペクターインスタンスが実行中でないか確認してください。
• サーバーが起動時にクラッシュする: すべての依存関係がインストールされていること (npm install)、Playwrightが設定されていること (npx playwright install chromium) を確認してください。

トラブルシューティング

• サーバーが起動しない: .env ファイルに GOOGLE_CUSTOM_SEARCH_API_KEY と GOOGLE_CUSTOM_SEARCH_ID が設定されていることを確認してください。どちらかが欠落している場合、サーバーは明確なエラーで終了します。
• スクレイピング結果が空の場合: 永続的なキャッシュに古いエントリが含まれている可能性があります。storage/persistent_cache/namespaces/scrapePage/ を削除し、再起動して新しいスクレイピングを強制的に行います。
• Playwright/Chromiumエラー: npx playwright install chromium を再実行してください。Linuxでは、システム依存関係のために npx playwright install-deps chromium も実行してください。Dockerでは、これらは事前にインストールされています。
• ポート3000が使用中: 他のプロセスを停止し (lsof -ti:3000 | xargs kill)、または PORT=3001 npm start を設定してください。
• YouTubeトランスクリプトが失敗する: 一部のビデオでは所有者によってトランスクリプトが無効にされている場合があります。エラーメッセージには具体的な理由 (例: TRANSCRIPT_DISABLED、VIDEO_UNAVAILABLE) が含まれています。すべてのエラーコードについては、YouTubeトランスクリプトドキュメント を参照してください。
• キャッシュの問題: /mcp/cache-stats を使用してキャッシュの健全性を確認するか、/mcp/cache-persist を使用して強制的に保存します。管理API を参照してください。
• OAuthエラー: .env ファイルの OAUTH_ISSUER_URL と OAUTH_AUDIENCE を確認してください。/mcp/oauth-config を使用して現在の設定を確認します。
• Dockerのヘルスチェックが失敗する: ヘルスチェックはポート3000の /health にアクセスします。これはHTTPトランスポートを必要とします。STDIOモード (MCP_TEST_MODE=stdio) では、ヘルスチェックは失敗します。これは正常な動作です。

ロードマップ

機能リクエストと改善点は GitHub Issues として追跡されています。貢献を歓迎します。

コントリビュート

あらゆる種類の貢献を歓迎します！詳細については コントリビューションガイド を参照してください。

📄 ライセンス

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