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 文件。