Google Research MCP

🚀 Google Researcher MCP Server

這是一款專業的AI助手研究工具，支持谷歌搜索、網頁抓取、學術論文搜索、專利搜索等功能，為AI研究和應用提供強大支持。

🚀 快速開始

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 中安裝。安裝過程中會提示你輸入谷歌 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 設置指南，獲取逐步指導以獲取谷歌 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   # 然後將你的谷歌 API 密鑰添加到 .env 文件中
npm run dev            # 服務器現在以 STDIO 傳輸模式運行

注意：這將以 STDIO 模式啟動服務器，這對於本地 AI 助手集成已經足夠。基於 Web 或多客戶端設置才需要使用帶有 OAuth 的 HTTP 傳輸模式 — 請參閱 選擇傳輸模式。

驗證是否正常工作

配置完成後，向你的 AI 助手提問：

"搜索關於 AI 法規的最新新聞"

助手將使用 google_news_search 工具並返回當前的文章。如果你看到搜索結果，則表示服務器正常工作。

✨ 主要特性

核心功能

MCP 協議支持

生產就緒

詳細文檔請參考：YouTube 字幕提取 · 架構 · 測試

📦 安裝指南

前提條件

• Node.js 版本 20.0.0 或更高
• 谷歌 API 密鑰：
  • 自定義搜索 API 密鑰
  • 自定義搜索引擎 ID
• Chromium（用於 JavaScript 渲染）：通過 npx playwright install chromium 自動安裝
• OAuth 2.1 提供商（僅 HTTP 傳輸模式需要）：一個外部授權服務器（如 Auth0、Okta），用於頒發 JWT。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 文件，添加你的谷歌 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 助手（大語言模型）提供的使用示例

推薦工具選擇

工具調用示例

// 研究某個主題（大多數查詢推薦使用）
{ "name": "search_and_scrape", "arguments": { "query": "2024 年氣候變化的影響", "num_results": 5 } }

// 帶跟蹤的多步驟研究（用於複雜調查）
{ "name": "sequential_search", "arguments": { "searchStep": "開始研究量子計算", "stepNumber": 1, "totalStepsEstimate": 4, "nextStepNeeded": true } }

// 查找學術論文（帶引用的同行評審來源）
{ "name": "academic_search", "arguments": { "query": "Transformer 神經網絡", "num_results": 5 } }

// 搜索專利（現有技術、自由實施分析）
{ "name": "patent_search", "arguments": { "query": "機器學習優化", "search_type": "prior_art" } }

// 獲取近期新聞
{ "name": "google_news_search", "arguments": { "query": "AI 法規", "freshness": "week" } }

// 查找圖片
{ "name": "google_image_search", "arguments": { "query": "太陽能電池板安裝", "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" } }

客戶端集成示例

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);

// 搜索谷歌
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 客戶端（Web 應用）

需要從配置的授權服務器獲取有效的 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);

📚 詳細文檔

可用工具

何時使用每個工具

工具參考

search_and_scrape（研究推薦工具）

一次調用即可搜索谷歌並從搜索結果中獲取內容。返回經過質量評分、去重的文本，並標註來源。響應中包含大小元數據（estimatedTokens、sizeCategory、truncated）。

google_search

返回谷歌搜索的排名 URL。當你只需要鏈接而不需要內容時使用。

google_image_search

使用過濾選項搜索谷歌圖片。

google_news_search

使用新鮮度和日期排序搜索谷歌新聞。

scrape_page

從任何 URL 提取文本。自動檢測：網頁（靜態/JS）、YouTube（字幕）、文檔（PDF/DOCX/PPTX）。

sequential_search

跟蹤多步驟研究狀態。遵循 sequential_thinking 模式：你負責推理，工具負責跟蹤狀態。

academic_search

通過谷歌自定義搜索 API 搜索學術論文，過濾到學術來源（arXiv、PubMed、IEEE、Nature、Springer 等）。返回帶預格式化引用的論文。

patent_search

在谷歌專利數據庫中進行現有技術搜索、自由實施分析和專利佈局。返回帶專利號、受讓人、發明人及 PDF 鏈接的專利。

系統架構

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 助手集成使用 STDIO 模式。僅在需要共享服務或 Web 應用集成時使用 HTTP+SSE 模式。

管理 API

管理和監控端點（僅 HTTP 傳輸模式可用）：

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: "量子計算", 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: "性能, 學習曲線, 生態系統" }
});

測試

所有 NPM 腳本：

測試理念和結構請參閱 測試指南。

開發工具

MCP Inspector

MCP Inspector 是一個用於 MCP 服務器的可視化調試工具。使用它可以交互式測試工具、瀏覽資源和驗證提示模板。

運行 Inspector：

npm run inspect

這將在瀏覽器中打開一個界面 http://localhost:5173，通過 STDIO 連接到服務器。

預期結果：

解決 Inspector 問題：

• “找不到模塊”錯誤：先運行 npm run build — Inspector 需要編譯後的 JavaScript。
• 工具調用因 API 錯誤失敗：確保 .env 文件中設置了 GOOGLE_CUSTOM_SEARCH_API_KEY 和 GOOGLE_CUSTOM_SEARCH_ID。
• 端口 5173 被佔用：Inspector UI 在端口 5173 上運行。停止使用該端口的其他服務，或者檢查是否有其他 Inspector 實例正在運行。
• 服務器啟動時崩潰：檢查所有依賴項是否已安裝（npm install），以及 Playwright 是否已設置（npx playwright install chromium）。

🔧 技術細節

安全

OAuth 2.1 授權

/mcp/ 下的所有 HTTP 端點（除公開文檔外）都受 OAuth 2.1 保護：

• 令牌驗證：JWT 會根據你的授權服務器的 JWKS 端點（${OAUTH_ISSUER_URL}/.well-known/jwks.json）進行驗證。
• 作用域強制：每個工具和管理操作都需要特定的 OAuth 作用域。

在 .env 文件中配置 OAUTH_ISSUER_URL 和 OAUTH_AUDIENCE。詳細信息請參閱 .env.example 文件。

STDIO 用戶：STDIO 傳輸模式不使用 OAuth。你可以跳過所有 OAuth 配置。

可用作用域

工具執行：

• mcp:tool:google_search:execute
• mcp:tool:google_image_search:execute
• mcp:tool:google_news_search:execute
• mcp:tool:scrape_page:execute
• mcp:tool:search_and_scrape:execute

管理：

• mcp:admin:cache:read
• mcp:admin:cache:invalidate
• mcp:admin:cache:persist
• mcp:admin:event-store:read
• mcp:admin:config:read

📄 許可證

本項目採用 MIT 許可證。詳情請參閱 LICENSE 文件。