STARWARCLOUD STARWAR.AI
返回市场
谷歌研究MCP服务器

谷歌研究MCP服务器

作者：zoharbabin7 星标更新：2025-07-16
安装使用来源：spider==github.com

项目介绍

Google Researcher MCP Server

Tests codecov License: MIT Node.js Version PRs Welcome

赋予AI助手强大的、持久且安全的网络研究能力。

该服务器实现了模型上下文协议（MCP），提供了一套工具用于Google搜索、内容抓取以及Gemini AI分析。它设计用于性能和可靠性，具有持久缓存系统、全面的超时处理和企业级安全性。

🎉 最新更新（v1.2.1）： 解决了scrape_page和research_topic工具返回占位测试内容而不是实际抓取数据的关键问题。现在所有工具均按预期返回真实网页内容。

<img width="499" alt="image" src="https://gips2.baidu.com/it/u=957238657,3033098892&fm=3081&app=3081&f=PNG?w=998&h=1026" />

目录

为什么使用此服务器？

  • 扩展AI能力：授予AI助手访问实时网络信息和强大分析工具的能力。
  • 最大化性能：通过复杂的两层持久缓存（内存和磁盘）大大减少重复查询的延迟。
  • 降低成本：通过缓存结果来最小化昂贵的Google搜索和Gemini API调用。
  • 确保可靠性：通过全面的超时处理和优雅降级来防止失败并确保一致的性能。
  • 灵活且安全的集成：通过STDIO或HTTP+SSE连接任何兼容MCP的客户端，并使用企业级OAuth 2.1进行安全API访问。
  • 开放且可扩展：MIT许可，完全开源，设计易于修改和扩展。

特性

  • 核心研究工具：
    • google_search：使用Google搜索API查找信息。
    • scrape_page：从网站和YouTube视频中提取内容，具有强大的字幕提取功能。
    • analyze_with_gemini：使用Google的强大Gemini AI模型处理文本。
    • research_topic：一个复合工具，将搜索、抓取和分析整合成一个高效的操作。
  • YouTube字幕提取：
    • 强大的YouTube字幕提取及全面错误处理：10种不同的错误类型，带有清晰的操作消息。
    • 智能重试逻辑及指数退避：自动重试瞬时失败（网络问题、速率限制、超时）。
    • 用户友好的错误消息及诊断：当字幕提取失败时，提供具体原因的明确反馈。
  • 高级缓存系统：
    • 双层缓存：结合快速的内存缓存以实现即时访问，以及持久的基于磁盘的缓存以实现耐用性。
    • 自定义命名空间：按工具组织缓存数据，防止冲突并简化管理。
    • 手动及自动持久化：提供基于时间的自动缓存保存和通过安全API端点的手动持久化。
  • 强大的性能与可靠性：
    • 全面超时：保护网络问题和外部API响应缓慢。
    • 优雅降级：即使工具或依赖项失败，也确保服务器保持响应。
    • 双重传输协议：支持本地进程通信的STDIO和适用于基于Web客户端的HTTP+SSE。
  • 企业级安全性：
    • OAuth 2.1保护：使用现代行业标准授权保护所有HTTP端点。
    • 细粒度范围：对工具和管理功能的访问提供精细控制。
  • 监控与管理：
    • 管理API：暴露端点以监控缓存统计信息、管理缓存和检查事件存储。

系统架构

服务器采用分层架构设计，旨在清晰、分离关注点和可扩展性。

graph TD
    subgraph "客户端"
        A[MCP客户端]
    end

    subgraph "传输层"
        B[STDIO]
        C[HTTP-SSE]
    end

    subgraph "核心逻辑"
        D{MCP请求路由器}
        E[工具执行器]
    end

    subgraph "工具"
        F[google_search]
        G[scrape_page]
        H[analyze_with_gemini]
        I[research_topic]
    end

    subgraph "支持系统"
        J[持久缓存]
        K[事件存储]
        L[OAuth中间件]
    end

    A -- 连接通过 --> B
    A -- 连接通过 --> C
    B -- 转发到 --> D
    C -- 转发到 --> D
    D -- 路由到 --> E
    E -- 调用 --> F
    E -- 调用 --> G
    E -- 调用 --> H
    E -- 调用 --> I
    F & G & H & I -- 使用 --> J
    D -- 使用 --> K
    C -- 受保护于 --> L

    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

更多详细解释，请参阅完整架构指南。

YouTube字幕提取

服务器包括一个强大的YouTube字幕提取系统，提供可靠访问视频字幕，具有全面的错误处理和自动恢复机制。

关键特性

  • 全面错误分类：识别10种不同错误类型，带有清晰的操作消息
  • 智能重试逻辑：瞬时失败的指数退避机制（最多3次尝试）
  • 生产优化：性能提升91%，日志减少80%
  • 用户友好反馈：当字幕提取失败时，提供明确的错误消息

支持的错误类型

错误代码描述用户操作
TRANSCRIPT_DISABLED视频所有者禁用了字幕尝试其他视频
VIDEO_UNAVAILABLE视频不再可用验证URL和视频状态
VIDEO_NOT_FOUND无效的视频ID或URL检查YouTube URL格式
NETWORK_ERROR网络连接问题系统会自动重试
RATE_LIMITEDYouTube API速率限制系统会自动重试并退避
TIMEOUT请求超时系统会自动重试
PARSING_ERROR字幕数据解析失败如果持续出现，请联系支持
REGION_BLOCKED视频在服务器区域被封锁如需，请使用代理
PRIVATE_VIDEO视频需要身份验证仅使用公共视频
UNKNOWN发生意外错误提供详细信息联系支持

重试行为

系统会自动重试瞬时错误的失败请求：

  • 最大尝试次数：对于NETWORK_ERROR、RATE_LIMITED和TIMEOUT，最多3次重试
  • 指数退避：重试之间的渐进延迟，避免过度请求YouTube的API
  • 智能恢复：仅重试可能在后续尝试中成功的错误

示例错误消息

当字幕提取失败时，用户会收到明确具体的错误消息：

无法检索https://www.youtube.com/watch?v=xxxx的YouTube字幕。
原因：TRANSCRIPT_DISABLED - 视频所有者已禁用字幕。

在3次尝试后，无法检索https://www.youtube.com/watch?v=xxxx的YouTube字幕。
原因：NETWORK_ERROR - 发生了网络错误。

完整技术细节，请参阅YouTube字幕提取文档。

开始使用

前提条件

安装与设置

  1. 克隆仓库：

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

  2. 安装依赖：

    npm install

  3. 配置环境变量： 复制示例文件并填写您的凭据。

    cp .env.example .env

    现在，在编辑器中打开.env并添加您的API密钥和OAuth配置。查看.env.example中的注释以了解每个变量的详细说明。

运行服务器

  • 开发模式： 对于开发，文件更改时自动重新加载，使用：

    npm run dev

    此命令使用tsx监视更改并重启服务器。

  • 生产模式： 首先，将TypeScript项目构建为JavaScript，然后启动服务器：

    npm run build
npm start

成功启动后，您将看到确认传输已准备就绪的消息：

✅ stdio传输已准备就绪
🌐 SSE服务器正在监听http://127.0.0.1:3000/mcp

使用方法

可用工具

服务器提供一套强大的工具用于研究和分析。每个工具都设计有详细的描述和注释，以便AI模型轻松理解和使用。

工具标题描述及参数
google_searchGoogle网络搜索描述：使用Google自定义搜索API搜索网络，找到相关网页和资源。适合查找当前信息、发现权威来源和定位特定文档。结果缓存30分钟。<br><br>参数：<br> - query（字符串，必需）：搜索查询。使用具体、有针对性的关键词以获得最佳结果。<br> - num_results（数字，可选，默认值：5）：要返回的搜索结果数量（1-10）。
scrape_page网页及YouTube内容提取器描述：从网页和YouTube视频中提取文本内容，具有强大的字幕提取功能。具有全面的错误处理，10种不同的错误类型（TRANSCRIPT_DISABLED、VIDEO_UNAVAILABLE、NETWORK_ERROR等），瞬时失败的自动重试逻辑及指数退避，以及用户友好的错误消息。支持youtube.com/watch?v=和youtu.be/ URL格式。结果缓存1小时。<br><br>参数：<br> - url（字符串，必需）：要抓取的网页或YouTube视频的URL。YouTube URL会自动提取可用的字幕。
analyze_with_geminiGemini AI文本分析描述：使用Google的Gemini AI模型处理和分析文本内容。它可以总结、回答问题并生成提供的文本见解。大文本会自动截断。结果缓存15分钟。<br><br>参数：<br> - text（字符串，必需）：要分析的文本内容。<br> - model（字符串，可选，默认值："gemini-2.0-flash-001"）：使用的Gemini模型（如gemini-2.0-flash-001、gemini-pro）。
research_topic综合主题研究工作流描述：一个强大的复合工具，自动化整个研究过程：它搜索主题，从多个来源抓取内容，并使用Gemini AI合成发现。它设计用于韧性，并提供全面分析。<br><br>参数：<br> - query（字符串，必需）：研究主题或问题。<br> - num_results（数字，可选，默认值：3）：要研究的来源数量（建议：2-5）。

客户端集成

STDIO客户端（本地进程）

适用于本地工具和CLI应用程序。

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: "test-client" });
await client.connect(transport);

const result = await client.callTool({
  name: "google_search",
  arguments: { query: "模型上下文协议" }
});
console.log(result.content[0].text);

// YouTube字幕提取示例
const youtubeResult = await client.callTool({
  name: "scrape_page",
  arguments: { url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }
});
console.log(youtubeResult.content[0].text);

HTTP+SSE客户端（Web应用）

适用于基于Web的客户端。需要有效的OAuth 2.1 Bearer令牌。

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

// 客户端必须从配置的外部授权服务器获取有效的OAuth 2.1 Bearer令牌，然后才能发出请求。
const transport = new StreamableHTTPClientTransport(
  new URL("http://localhost:3000/mcp"),
  {
    getAuthorization: async () => `Bearer YOUR_ACCESS_TOKEN`
  }
);
const client = new Client({ name: "test-client" });
await client.connect(transport);

const result = await client.callTool({
  name: "google_search",
  arguments: { query: "模型上下文协议" }
});
console.log(result.content[0].text);

// YouTube字幕提取带错误处理
try {
  const youtubeResult = await client.callTool({
    name: "scrape_page",
    arguments: { url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }
  });
  console.log("字幕：", youtubeResult.content[0].text);
} catch (error) {
  if (error.content && error.content[0].text.includes("TRANSCRIPT_DISABLED")) {
    console.log("视频所有者已禁用字幕");
  } else if (error.content && error.content[0].text.includes("VIDEO_NOT_FOUND")) {
    console.log("未找到视频 - 检查URL");
  } else {
    console.log("字幕提取失败：", error.content[0].text);
  }
}

管理API

服务器提供了几个用于监控和控制的管理端点。这些端点的访问受OAuth范围保护。

方法端点描述所需范围
GET/mcp/cache-stats查看缓存性能统计信息。mcp:admin:cache:read
GET/mcp/event-store-stats查看事件存储使用统计信息。mcp:admin:event-store:read
POST/mcp/cache-invalidate清除特定缓存条目。mcp:admin:cache:invalidate
POST/mcp/cache-persist强制缓存保存到磁盘。mcp:admin:cache:persist
GET/mcp/oauth-scopes获取所有OAuth范围的文档。公开
GET/mcp/oauth-config查看服务器的OAuth配置。m_：admin:config:read
GET/mcp/oauth-token-info查看提供的令牌详情。需要认证

性能与可靠性

服务器经过优化，适用于生产使用，具有显著的性能改进和可靠性增强：

YouTube字幕提取性能

  • 91%性能提升：YouTube字幕提取的端到端测试现在快了91%
  • 80%日志减少：精简的日志减少了噪音，同时保持诊断能力
  • 生产控制：基于环境的配置允许微调重试行为和超时