STARWARCLOUD STARWAR.AI
返回市场
搜索引擎API-MCP服务器

搜索引擎API-MCP服务器

作者：serpapi19 星标更新：2025-11-21
安装使用来源：spider==github.com

项目介绍

<img src="https://gips0.baidu.com/it/u=2286615059,3031345639&fm=3081&app=3081&f=PNG?w=512&h=512" width="30" height="30"/> SerpApi MCP Server

这是一个与SerpApi集成的模型上下文协议（MCP）服务器实现，用于全面的搜索引擎结果和数据提取。

构建 Python 3.13+ MIT 许可证

特性

  • 多引擎搜索：支持Google、Bing、Yahoo、DuckDuckGo、Yandex、百度、YouTube、eBay、沃尔玛等
  • 实时天气数据：基于位置的天气预报通过搜索查询获取
  • 股市数据：通过搜索集成获取公司财务和市场数据
  • 动态结果处理：自动检测并格式化不同类型的搜索结果
  • 原始JSON支持：选项返回完整的未处理API响应
  • 结构化结果：优化AI消费的干净、格式化的输出
  • 速率限制处理：带有指数退避的自动重试逻辑
  • 错误恢复：全面的错误处理和用户反馈

安装

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

配置

API密钥认证

此服务器支持两种提供您的SerpApi API密钥的方法：

  1. 路径基础（推荐）：在URL路径中直接包含您的API密钥
  2. 头部基础：在Authorization头部传递您的API密钥

必需项

设置步骤

  1. 获取API密钥：在SerpApi注册并获取您的API密钥
  2. 运行服务器： 
    uv run src/server.py
  3. 使用API密钥访问：使用以下任一方法进行请求认证

使用Docker运行

# 构建镜像
docker build -t serpapi-mcp-server .

# 运行容器（不需要环境变量）
docker run -p 8000:8000 serpapi-mcp-server

服务器将在http://localhost:8000可用。按照下面所示，在请求路径或头部中包含您的API密钥。

客户端配置

Claude Desktop

方法1：路径基础API密钥（推荐）

添加到您的claude_desktop_config.json：

{
  "mcpServers": {
    "serpapi": {
      "url": "http://localhost:8000/YOUR_SERPAPI_API_KEY/v1/mcp"
    }
  }
}

方法2：授权头部

添加到您的claude_desktop_config.json：

{
  "mcpServers": {
    "serpapi": {
      "url": "http://localhost:8000/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SERPAPI_API_KEY"
      }
    }
  }
}

生产部署

对于生产部署，请使用您的域名：

{
  "mcpServers": {
    "serpapi": {
      "url": "https://yourdomain.com/YOUR_SERPAPI_API_KEY/v1/mcp"
    }
  }
}

认证示例

cURL示例

路径基础认证

curl -X POST "http://localhost:8000/your_serpapi_key/v1/mcp" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/call", "params": {"name": "search", "arguments": {"params": {"q": "伦敦天气"}}}}'

头部基础认证

curl -X POST "http://localhost:8000/v1/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_serpapi_key" \
  -d '{"method": "tools/call", "params": {"name": "search", "arguments": {"params": {"q": "伦敦天气"}}}}'

客户端库示例

两种认证方式均可无缝与MCP客户端配合使用。服务器会自动检测并验证您从URL路径或Authorization头部提供的API密钥。

可用工具

统一搜索工具（search）

一个统一的搜索工具，通过单一接口处理所有类型的搜索。

最佳用途：

  • 任何类型的搜索查询（网络、天气、股票、图片、新闻、购物）
  • 所有搜索引擎和结果类型的一致界面
  • 格式化输出和原始JSON响应

参数：

  • params (字典)：搜索参数包括：
    • q (字符串)：搜索查询（必需）
    • engine (字符串)：搜索引擎（默认："google_light"）
    • location (字符串)：地理位置过滤器
    • num (整数)：结果数量（默认：110）
  • raw (布尔值)：返回原始JSON响应（默认：false）

使用示例：

通用搜索

{
  "name": "search",
  "arguments": {
    "params": {
      "q": "最好的咖啡店",
      "engine": "google",
      "location": "德克萨斯州奥斯汀"
    }
  }
}

天气搜索

{
  "name": "search",
  "arguments": {
    "params": {
      "q": "伦敦天气",
      "engine": "google"
    }
  }
}

股票市场搜索

{
  "name": "search",
  "arguments": {
    "params": {
      "q": "AAPL股价",
      "engine": "google"
    }
  }
}

新闻搜索

{
  "name": "search",
  "arguments": {
    "params": {
      "q": "最新的人工智能发展",
      "engine": "google",
      "tbm": "nws"
    }
  }
}

原始JSON输出

{
  "name": "search",
  "arguments": {
    "params": {
      "q": "机器学习",
      "engine": "google"
    },
    "raw": true
  }
}

支持的搜索引擎

  • Google (google) - 全面的Google搜索结果
  • Google轻量版 (google_light) - 更快、更轻量的Google搜索结果（默认）
  • Bing (bing) - Microsoft Bing搜索
  • Yahoo (yahoo) - Yahoo搜索结果
  • DuckDuckGo (duckduckgo) - 注重隐私的搜索
  • Yandex (yandex) - 俄罗斯搜索引擎
  • 百度 (baidu) - 中国搜索引擎
  • YouTube (youtube_search) - 视频搜索
  • eBay (ebay) - 产品搜索
  • 沃尔玛 (walmart) - 产品搜索

完整列表，请访问SerpApi Engines。

结果类型

搜索工具会自动检测并格式化不同的结果类型：

  • 答案框：天气数据、股票价格、知识图谱、计算结果
  • 自然搜索结果：传统的网页搜索结果
  • 新闻结果：带来源和日期的新闻文章
  • 图片结果：带缩略图和链接的图片
  • 购物结果：带价格和来源的产品列表

结果被优先级排序并格式化以优化可读性。

错误处理

服务器提供了全面的错误处理：

  • 速率限制：带有指数退避的自动重试
  • 认证：清晰的API密钥验证消息
  • 网络问题：优雅降级和错误报告
  • 无效参数：有用的参数验证

常见错误响应：

{
  "error": "超出速率限制。请稍后再试。"
}

开发

在开发模式下运行

# 安装依赖
uv sync

# 直接运行服务器
uv run src/server.py

使用MCP Inspector

MCP Inspector提供了一个测试MCP工具的Web界面。

# 安装（需要Node.js）
npm install -g @modelcontextprotocol/inspector

# 运行检查器
npx @modelcontextprotocol/inspector

然后配置：

  • 路径基础：URL localhost:8000/YOUR_API_KEY/v1/mcp，传输“流式HTTP传输”
  • 头部基础：URL localhost:8000/v1/mcp，传输“流式HTTP传输”，并在Authorization头部添加 Bearer YOUR_API_KEY

点击“列出工具”开始测试。

项目结构

serpapi-mcp-server/
├── src/
│   └── server.py           # 主要的MCP服务器实现
├── pyproject.toml         # 项目配置  
├── README.md              # 此文件
├── LICENSE               # MIT许可证
└── .env.example          # 环境模板

使用示例

基本搜索

# 搜索信息
result = await client.call_tool("search", {
    "params": {
        "q": "MCP协议文档",
        "engine": "google"
    }
})

天气查询

# 获取天气信息
weather = await client.call_tool("search", {
    "params": {
        "q": "旧金山天气预报",
        "engine": "google"
    }
})

股票信息

# 获取股票数据
stock = await client.call_tool("search", {
    "params": {
        "q": "特斯拉股价和市值",
        "engine": "google"
    }
})

原始JSON响应

# 获取完整的API响应
raw_data = await client.call_tool("search", {
    "params": {
        "q": "人工智能",
        "engine": "google"
    },
    "raw": True
})

故障排除

常见问题

“缺少API密钥”错误：

  • 确保您的API密钥包含在URL路径中：/{YOUR_API_KEY}/v1/mcp
  • 或者验证Authorization头部：Bearer YOUR_API_KEY
  • 在serpapi.com/manage-api-key验证您的API密钥

“无效的SerpApi API密钥”错误：

  • 检查您的API密钥是否有效：serpapi.com/manage-api-key
  • 确保路径或头部中的API密钥格式正确
  • 验证您的SerpApi订阅是否处于活动状态

“超出速率限制”错误：

  • 等待重试期
  • 考虑升级您的SerpApi计划
  • 减少请求频率

“模块未找到”错误：

  • 确保已安装依赖项：uv install 或 pip install mcp serpapi python-dotenv
  • 检查Python版本兼容性（需要3.13+）

“未找到结果”错误：

  • 尝试调整您的搜索查询
  • 使用不同的搜索引擎
  • 检查所选引擎是否支持该查询

贡献

  1. 分叉仓库
  2. 创建功能分支：git checkout -b feature/amazing-feature
  3. 安装依赖项：uv install
  4. 进行更改
  5. 提交更改：git commit -m '添加惊人的功能'
  6. 推送到分支：git push origin feature/amazing-feature
  7. 打开拉取请求

许可证

MIT许可证 - 详情请参阅LICENSE文件。