SerpApi MCP Server - Python

SerpApi MCP 服务 - Python

一组与 SerpAPI 和 YouTube 集成的模型上下文协议（MCP）服务，可为 AI 助手提供搜索功能和数据检索能力。

概述

本项目提供了多个 MCP 服务，使 Claude 等 AI 助手能够执行各种搜索操作，并检索以下来源的数据：

• Google Search
• Google News
• Google Scholar
• Google Trends
• Google Finance
• Google Maps
• Google Images
• YouTube Search
• YouTube Transcripts

每个服务都旨在与模型上下文协议（MCP）配合使用，可轻松集成到支持此协议的 AI 助手中，例如 Claude for Desktop 或 Grok。

功能

• Google Search（serpapi_google_search.py）
• Google News（serpapi_google_news.py）
• Google Scholar（serpapi_google_scholar.py）
• Google Trends（serpapi_google_trend.py）
• Google Finance（serpapi_google_finance.py）
• Google Maps（serpapi_google_maps.py）
• Google Images（serpapi_google_images.py）
• YouTube Search（serpapi_youtube_search.py）
• YouTube Transcript（youtube_transcript.py）

安装

先决条件

• Python 3.8 或更高版本
• SerpAPI API 密钥（可在 serpapi.com 获取）

设置

1. 克隆代码仓库：

git clone https://github.com/yourusername/serpapi-mcp-server.git
cd serpapi-mcp-server

2. 创建虚拟环境并安装依赖项：

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. 根据提供的 .env.example，在项目根目录中创建 .env 文件：

cp .env.example .env

4. 编辑 .env 文件并添加你的 SerpAPI API 密钥：

SERPAPI_API_KEY=your_api_key_here

快速开始

1. 保存服务代码：将服务代码放入一个文件中，例如 server.py。

2. 配置 API 密钥：在同一目录中创建 .env 文件，并填入你的 SerpApi API 密钥：

SERPAPI_API_KEY=your_api_key_here

3. 运行服务：使用以下命令启动服务：

python src/serpapi_google_search.py  # Or any other server file

4. 与 MCP 客户端集成：将服务连接到 MCP 客户端或宿主端（例如 Claude for Desktop）。

在 Claude for Desktop 中使用

1. 将这些 MCP 服务添加到 claude_desktop_config.json 文件中，配置 Claude for Desktop 以使用它们：

{
  "mcpServers": {
    "serpapi-google-search": {
      "type": "stdio",
      "command": "path/to/python",
      "args": [
        "path/to/serpapi-mcp-server/src/serpapi_google_search.py"
      ],
      "env": {
        "PYTHONPATH": "path/to/site-packages"
      }
    },
    "serpapi-youtube-search": {
      "type": "stdio",
      "command": "path/to/python",
      "args": [
        "path/to/serpapi-mcp-server/src/serpapi_youtube_search.py"
      ],
      "env": {
        "PYTHONPATH": "path/to/site-packages"
      }
    },
    "serpapi-google-news": {
      "type": "stdio",
      "command": "path/to/python",
      "args": [
        "path/to/serpapi-mcp-server/src/serpapi_google_news.py"
      ],
      "env": {
        "PYTHONPATH": "path/to/site-packages"
      }
    },
    "serpapi-google-trend": {
      "type": "stdio",
      "command": "path/to/python",
      "args": [
        "path/to/serpapi-mcp-server/src/serpapi_google_trend.py"
      ],
      "env": {
        "PYTHONPATH": "path/to/site-packages"
      }
    },
    "serpapi-google-scholar": {
      "type": "stdio",
      "command": "path/to/python",
      "args": [
        "path/to/serpapi-mcp-server/src/serpapi_google_scholar.py"
      ],
      "env": {
        "PYTHONPATH": "path/to/site-packages"
      }
    },
    "serpapi-google-finance": {
      "type": "stdio",
      "command": "path/to/python",
      "args": [
        "path/to/serpapi-mcp-server/src/serpapi_google_finance.py"
      ],
      "env": {
        "PYTHONPATH": "path/to/site-packages"
      }
    },
    "serpapi-google-maps": {
      "type": "stdio",
      "command": "path/to/python",
      "args": [
        "path/to/serpapi-mcp-server/src/serpapi_google_maps.py"
      ],
      "env": {
        "PYTHONPATH": "path/to/site-packages"
      }
    },
    "serpapi-google-images": {
      "type": "stdio",
      "command": "path/to/python",
      "args": [
        "path/to/serpapi-mcp-server/src/serpapi_google_images.py"
      ],
      "env": {
        "PYTHONPATH": "path/to/site-packages"
      }
    },
    "youtube-transcript": {
      "type": "stdio",
      "command": "path/to/python",
      "args": [
        "path/to/serpapi-mcp-server/src/youtube_transcript.py"
      ],
      "env": {
        "PYTHONPATH": "path/to/site-packages"
      }
    }
  }
}

2. 确保已在项目根目录中的 .env 文件里设置 SerpAPI 密钥。

3. 重启 Claude for Desktop 以加载新配置。

4. 现在，你可以在与 Claude 的对话中直接使用这些搜索功能。

查询示例

以下是如何在 Claude Desktop 中使用这些服务的一些示例：

Google Search

Please search for "climate change solutions" and summarize the top results.

Google News

Find the latest news about artificial intelligence.

Google Scholar

Find recent academic papers on quantum computing.

Google Trends

What are the trending topics in technology right now?

Google Finance

Look up the current stock price and financial information for Apple (AAPL).

Google Maps

Find coffee shops near Central Park, New York.

Google Images

Search for images of "northern lights" and describe what you see.

YouTube Search

Search for tutorial videos on Python programming.

YouTube Transcript

Get the transcript of this YouTube video: https://www.youtube.com/watch?v=dQw4w9WgXcQ

API 参数

每个服务都支持多种参数，可用于微调搜索。以下列出了每个服务的所有参数：

Google Search

• q：搜索查询
• num：结果数量（1-100）
• start：分页结果偏移量（索引从 1 开始）
• location：搜索所在位置
• gl：Google 搜索的国家/地区代码（例如 'us'、'uk'）
• hl：语言代码（例如 'en'、'es'）
• device：设备类型（'desktop'、'mobile'、'tablet'）
• safe：安全搜索设置（'active'、'off'）
• filter：过滤重复内容（'0' 表示关闭，'1' 表示开启）
• time_period：按时效筛选（例如 'd' 表示过去一天）
• exactTerms：必须精确出现的单词或短语
• include_domains：要包含在搜索结果中的域名列表
• exclude_domains：要从搜索结果中排除的域名列表
• raw_json：返回完整的原始 JSON 响应（布尔值）
• readable_json：以 Markdown 格式的文本返回结果（布尔值）

Google Search API 参数完整文档

Google 新闻

• q：搜索查询
• gl：国家代码（例如，'us'、'uk'）
• hl：语言代码（例如，'en'、'es'）
• publication_token：在特定出版物中搜索
• topic_token：在特定主题中搜索
• story_token：获取特定新闻故事的完整报道
• section_token：在特定版块中搜索
• so：排序方式（'0' 表示相关性，'1' 表示日期）
• raw_json：返回完整的原始 JSON 响应（布尔值）
• readable_json：以 Markdown 格式的文本返回结果（布尔值）

Google 新闻 API 参数完整文档

Google Scholar

• q：搜索查询
• hl：语言代码（例如，'en'、'es'）
• lr：语言限制（例如，'lang_fr|lang_de'）
• start：分页结果偏移量
• num：结果数量（1-20）
• cites：被引用搜索的 ID
• as_ylo：时间范围的起始年份
• as_yhi：时间范围的结束年份
• scisbd：按日期排序（0 表示相关性，1 表示摘要，2 表示全部内容）
• cluster：所有版本搜索的 ID
• as_sdt：搜索类型或筛选条件
• safe：安全搜索设置（'active'、'off'）
• filter：相似结果或省略结果筛选（'0' 表示关闭，'1' 表示开启）
• as_vis：是否包含引用（'0' 表示包含，'1' 表示排除）
• as_rr：仅显示综述文章（'0' 表示全部，'1' 表示仅综述）
• raw_json：返回完整的原始 JSON 响应（布尔值）
• readable_json：以 Markdown 格式的文本返回结果（布尔值）

Google Scholar API 参数完整文档

Google Trends

• q：搜索查询（可用逗号分隔多个查询）
• geo：地理位置（例如，'US'、'GB'）
• date：时间范围（例如，'now 1-d'、'now 7-d'、'today 12-m'）
• tz：时区偏移量（分钟）
• data_type：搜索类型（例如，'TIMESERIES'、'GEO_MAP'）
• cat：类别 ID
• gprop：属性筛选条件（例如，'web'、'news'、'images'）
• raw_json：返回完整的原始 JSON 响应（布尔值）
• readable_json：以 Markdown 格式的文本返回结果（布尔值）

Google Trends API 参数完整文档

Google Finance

• q：股票、指数、共同基金、货币或期货的搜索查询
• hl：语言代码（例如，'en'、'es'）
• window：图表时间范围（例如，'1D'、'5D'、'1M'、'6M'、'YTD'、'1Y'、'5Y'、'MAX'）
• raw_json：返回完整的原始 JSON 响应（布尔值）
• readable_json：以 Markdown 格式的文本返回结果（布尔值）

Google Finance API 参数完整文档

Google Maps

• q：搜索查询
• type：搜索类型（'search' 或 'place'）
• place_id：Google Maps 上地点的唯一引用标识
• data：筛选搜索结果或搜索特定地点
• ll：GPS 坐标，格式为 '@latitude,longitude,zoom'
• google_domain：要使用的 Google 域名（默认为 google.com）
• hl：语言代码（例如，'en'、'es'）
• gl：国家代码（例如，'us'、'uk'）
• start：分页结果偏移量（整数）
• raw_json：返回完整的原始 JSON 响应（布尔值）
• readable_json：以 Markdown 格式的文本返回结果（布尔值）

Google Maps API 参数完整文档

Google Images

• q：搜索查询
• location：搜索位置
• uule：Google 编码后的位置（不能与 location 一起使用）
• google_domain：要使用的 Google 域名（默认为 google.com）
• hl：语言代码（例如，'en'、'es'）
• gl：国家/地区代码（例如，'us'、'uk'）
• cr：国家/地区限制（例如，'countryUS'）
• device：设备类型（'desktop'、'tablet'、'mobile'）
• ijn：页码（从零开始的索引）
• chips：Google 提供的建议搜索筛选字符串
• tbs：高级搜索参数
• imgar：图像宽高比（'s' - 正方形，'t' - 竖向，'w' - 横向，'xw' - 全景）
• imgsz：图像尺寸（'l' - 大，'m' - 中，'i' - 图标等）
• image_color：图像颜色（'red'、'blue'、'green'、'black'、'white' 等）
• image_type：图像类型（'face'、'photo'、'clipart'、'lineart'、'animated'）
• licenses：许可范围（'f' - 免费使用，'fc' - 免费商用等）
• safe：安全搜索设置（'active'、'off'）
• nfpr：排除自动更正的结果（'1' 表示排除，'0' 表示包含）
• filter：启用/禁用“相似结果”和“已省略结果”筛选器
• time_period：按新近程度筛选（例如，'d' 表示过去一天）
• raw_json：返回完整的原始 JSON 响应（布尔值）
• readable_json：以 Markdown 格式文本返回结果（布尔值）

Google Images API 参数完整文档

YouTube 搜索

• search_query：搜索查询
• gl：国家/地区代码（例如，'us'、'uk'）
• hl：语言代码（例如，'en'、'es'）
• sp：筛选参数（例如，'CAISAhAB' 表示今天上传的视频）
• raw_json：返回完整的原始 JSON 响应（布尔值）
• readable_json：以 Markdown 格式文本返回结果（布尔值）

YouTube Search API 参数完整文档

YouTube 视频

• v：YouTube 视频 ID
• gl：国家/地区代码（例如，'us'、'uk'）
• hl：语言代码（例如，'en'、'es'）
• next_page_token：用于获取下一页相关视频、评论或回复的令牌
• raw_json：返回完整的原始 JSON 响应（布尔值）
• readable_json：以 Markdown 格式文本返回结果（布尔值）

YouTube 字幕稿

• video_url：YouTube 视频 URL 或 ID
• with_timestamps：在字幕稿中包含时间戳（布尔值）
• language：字幕稿的语言代码（默认值：'en'）
• preserve_formatting：保留 HTML 格式元素（布尔值）
• cookies_path：受年龄限制视频的 cookies.txt 文件路径
• proxy：请求使用的 HTTPS 代理
• raw_json：返回完整的原始 JSON 响应（布尔值）
• readable_json：返回人类可读的格式化文本（布尔值）
• text_transcript：将字幕稿作为单个文本字符串返回（布尔值）

YouTube Transcript API 文档

故障排除

API 密钥无效

• 验证 .env 文件中的 API 密钥配置
• 确认 API 密钥在 SerpAPI 控制面板中处于有效状态
• 检查 API 密钥中是否包含引号或空格

请求失败

• 检查网络连接
• 确认 API 调用配额尚未超出
• 验证请求参数格式
• 检查是否存在速率限制问题

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• 感谢 SerpApi 提供搜索 API
• 感谢 YouTube Transcript API 提供字幕稿检索功能
• 感谢 MCP 协议支持 AI 助手集成

资源

• SerpAPI 文档
• MCP 协议文档
• Claude 桌面版文档