星战科技xingzhan.cloud
返回市场
搜索API-mcp

搜索API-mcp

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

项目介绍

SearchAPI MCP Server

<div align="center">

License: MIT Python 3.10+ FastMCP

一个基于 Model Context Protocol (MCP) 的生产级搜索服务器，通过 SearchAPI.io 提供全面的搜索功能。使 AI 助手能够搜索 Google、地图、航班、酒店等，内置缓存、重试逻辑和熔断器。

特性 • 快速开始 • 安装 • 配置 • 可用工具

</div>

特性

🔍 搜索引擎

  • Google 搜索 - 网页结果、知识图谱、答案框、相关问题
  • Google 视频 - 按时长、来源和上传时间过滤视频搜索
  • Google AI 模式 - 引用来源和结构化内容生成的 AI 概述
  • Google 地图 - 地点、企业、评论和位置详情
  • Google 地图地点 - 具体位置的详细信息（营业时间、照片、设施）
  • Google 活动 - 查找音乐会、会议、节日和当地活动
  • Google 航班 - 综合筛选和价格日历的航班搜索
  • Google 航班地点搜索 - 机场代码查询和自动补全
  • Google 旅行探索 - 发现目的地和旅行灵感
  • Google 酒店 - 带有设施、评分和价格筛选的住宿搜索

🏗️ 生产级架构

  • 连接池 - 使用 httpx 进行高效的 HTTP 连接管理
  • 响应缓存 - 基于 TTL 的缓存，LRU 节点替换策略
  • 重试逻辑 - 对短暂失败的指数退避重试
  • 熔断器 - 防止级联故障的容错模式
  • 指标收集 - 请求计数、延迟、缓存命中率、错误跟踪
  • 健康检查 - 监控 API 连接性和服务状态

⚙️ 配置与监控

  • Pydantic 验证 - 支持环境变量的类型安全配置
  • 结构化日志 - 可配置的日志级别和详细的请求追踪
  • 资源管理 - 自动清理和优雅关闭
  • 环境变量 - 不同部署的灵活配置

快速开始

先决条件

  • Python 3.10 或更高版本
  • SearchAPI.io API 密钥 (获取密钥)

使用 UV 安装（推荐）

最快的方式是使用 uvx：

# 设置你的 API 密钥
export SEARCHAPI_API_KEY="your_api_key_here"

# 直接使用 uvx 运行（无需安装）
uvx --from git+https://github.com/RmMargt/searchAPI-mcp.git mcp-server-searchapi

安装

方法 1：UV（推荐）

UV 是最快且最方便的方法：

# 如果尚未安装，请安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆仓库
git clone https://github.com/RmMargt/searchAPI-mcp.git
cd searchAPI-mcp

# 安装依赖项
uv pip install -r requirements.txt

方法 2：pip

# 克隆仓库
git clone https://github.com/RmMargt/searchAPI-mcp.git
cd searchAPI-mcp

# 创建并激活虚拟环境
python -m venv venv
source venv/bin/activate  # 在 Windows 上：.\venv\Scripts\activate

# 安装依赖项
pip install -r requirements.txt

方法 3：从源码安装

git clone https://github.com/RmMargt/searchAPI-mcp.git
cd searchAPI-mcp

# 使用 uv
uv pip install httpx fastmcp python-dotenv pydantic pydantic-settings

# 或者使用 pip
pip install httpx fastmcp python-dotenv pydantic pydantic-settings

配置

环境变量

在项目根目录创建一个 .env 文件：

# 必需
SEARCHAPI_API_KEY=your_api_key_here

# 可选 - API 配置
SEARCHAPI_API_URL=https://www.searchapi.io/api/v1/search
TIMEOUT=30.0
MAX_RETRIES=3
RETRY_BACKOFF=1.0

# 可选 - 缓存配置
ENABLE_CACHE=true
CACHE_TTL=3600
CACHE_MAX_SIZE=1000

# 可选 - 连接池
POOL_CONNECTIONS=10
POOL_MAXSIZE=10

# 可选 - 监控
ENABLE_METRICS=true
LOG_LEVEL=INFO

MCP 客户端配置

Claude Desktop

添加到你的 Claude Desktop 配置文件中：

位置：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

使用 UV（推荐）：

{
  "mcpServers": {
    "searchapi": {
      "command": "uvx",
      "args": [
        "--directory",
        "/absolute/path/to/searchAPI-mcp",
        "python",
        "mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

直接使用 Python：

{
  "mcpServers": {
    "searchapi": {
      "command": "python",
      "args": [
        "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

使用虚拟环境：

{
  "mcpServers": {
    "searchapi": {
      "command": "/absolute/path/to/searchAPI-mcp/venv/bin/python",
      "args": [
        "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

VS Code (Continue, Cline)

添加到 .vscode/mcp.json 中或使用“MCP: 打开用户配置”命令：

{
  "servers": {
    "searchapi": {
      "command": "python",
      "args": [
        "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

使用 UV：

{
  "servers": {
    "searchapi": {
      "command": "uvx",
      "args": [
        "--directory",
        "/absolute/path/to/searchAPI-mcp",
        "python",
        "mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Zed Editor

添加到 ~/.config/zed/settings.json：

{
  "context_servers": {
    "searchapi": {
      "command": {
        "path": "python",
        "args": [
          "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
        ],
        "env": {
          "SEARCHAPI_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

Cline (VS Code 扩展)

在 Cline 设置中添加到 MCP 服务器：

{
  "mcpServers": {
    "searchapi": {
      "command": "python",
      "args": [
        "/absolute/path/to/searchAPI-mcp/mcp_server_refactored.py"
      ],
      "env": {
        "SEARCHAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

通用 MCP 客户端

对于任何兼容 MCP 的客户端：

# 使用 stdio 传输（默认）
python /path/to/searchAPI-mcp/mcp_server_refactored.py

# 使用环境变量
SEARCHAPI_API_KEY=your_key python mcp_server_refactored.py

可用工具

健康与监控

health_check

检查 SearchAPI 服务的健康状况和性能。

返回值：

  • API 连接状态
  • 响应延迟
  • 熔断器状态
  • 缓存统计
  • 请求指标

示例：

{
  "api_status": {
    "status": "healthy",
    "latency_ms": 145.23,
    "circuit_breaker": "closed"
  },
  "cache_stats": {
    "size": 42,
    "max_size": 1000,
    "ttl": 3600
  },
  "metrics": {
    "request_count": 156,
    "error_count": 2,
    "cache_hit_rate": 0.67
  }
}

时间与日期工具

get_current_time

获取当前时间和旅行日期建议。对于航班和酒店预订至关重要。

参数：

  • format - 日期格式："iso", "slash", "chinese", "timestamp", "full"
  • days_offset - 从今天起的天数（可以是负数）
  • return_future_dates - 返回未来日期数组
  • future_days - 未来日期的数量（如果 return_future_dates=true）

示例：

# 获取今天的日期，ISO 格式
get_current_time(format="iso")
# 返回：{"date": "2025-11-16", "now": {...}, "travel_dates": {...}}

# 获取 7 天后的时间以及未来日期数组
get_current_time(days_offset=7, return_future_dates=True, future_days=30)

Google 搜索

search_google

搜索 Google 的网页结果、知识图谱和答案框。

参数：

  • q (必需) - 搜索查询
  • location - 地点名称（例如，“纽约，纽约”）
  • gl - 国家代码（默认："us"）
  • hl - 语言代码（默认："en"）
  • time_period - 时间筛选："last_hour", "last_day", "last_week", "last_month", "last_year"
  • num - 每页结果数量（默认："10"）
  • safe - 安全搜索："off", "active"

示例：

search_google(
    q="Python 编程教程",
    location="旧金山, 加利福尼亚州",
    time_period="last_month",
    num="20"
)

search_google_videos

搜索 Google 视频内容。

参数： 类似于 search_google，但有视频特定的筛选条件

  • q (必需) - 搜索查询
  • time_period - 按上传时间筛选
  • device - "desktop" 或 "mobile"

示例：

search_google_videos(
    q="机器学习教程",
    time_period="last_week",
    num="10"
)

search_google_ai_mode

使用 AI 生成的概述和引用来源进行搜索。

参数：

  • q - 搜索查询（除非提供 url，否则必需）
  • url - 图像 URL 以进行搜索
  • location - 本地化结果的位置

返回值：

  • AI 生成的概述及引用
  • 结构化内容块（段落、列表、表格、代码）
  • 参考链接
  • 网页结果

示例：

search_google_ai_mode(
    q="机器学习是如何工作的？",
    location="美国"
)

Google 地图

search_google_maps

搜索地点、企业和服务。

参数：

  • query (必需) - 搜索查询
  • location_ll - 经纬度坐标（格式："@lat,lng,zoom"）

示例：

search_google_maps(
    query="中央公园附近的咖啡馆",
    location_ll="@40.7829,-73.9654,15z"
)

search_google_maps_place

获取特定地点的详细信息。

参数：

  • place_id (如果没有 data_id，则必需) - Google 地图地点 ID
  • data_id - 替代地点标识符
  • google_domain - Google 域名（默认："google.com"）
  • hl - 语言代码（默认："en"）

示例：

search_google_maps_place(
    place_id="ChIJN1t_tDeuEmsRUsoyG83frY4"
)

search_google_maps_reviews

获取特定地点的评论。

参数：

  • place_id (如果没有 data_id，则必需) - Google 地图地点 ID
  • data_id - 替代地点标识符
  • sort_by - "most_relevant", "newest", "highest_rating", "lowest_rating"
  • rating - 按评分筛选："1"-"5"

示例：

search_google_maps_reviews(
    place_id="ChIJN1t_tDeuEmsRUsoyG83frY4",
    sort_by="newest",
    rating="5"
)

Google 活动

search_google_events

搜索活动、音乐会、会议和活动。

参数：

  • q (必需) - 搜索查询（例如，“纽约市音乐会”，“科技会议”）
  • location - 用于本地化结果的地点名称
  • chips - 日期筛选（"today", "tomorrow", "week", "weekend", "month"）或活动类型
  • gl - 国家代码（默认："us"）
  • hl - 语言代码（默认："en"）
  • page - 页码（默认："1"）

示例：

search_google_events(
    q="奥斯汀音乐节",
    chips="weekend",
    location="奥斯汀, 德克萨斯州"
)

Google 航班

search_google_flights

搜索航班，带有综合筛选。

参数：

  • departure_id (必需) - 机场代码（例如，“JFK”）
  • arrival_id (必需) - 机场代码（例如，“LAX”）
  • outbound_date (必需) - 出发日期（YYYY-MM-DD）
  • flight_type - "one_way", "round_trip", "multi_city"
  • return_date - 回程日期（往返行程必需）
  • travel_class - "economy", "premium_economy", "business", "first"
  • stops - "0"（直飞），"1"，"2"
  • adults - 成人人数
  • currency - 货币代码（例如，“USD”）

示例：

search_google_flights(
    departure_id="JFK",
    arrival_id="LAX",
    outbound_date="2025-12-15",
    return_date="2025-12-22",
    flight_type="round_trip",
    travel_class="economy",
    stops="0",
    adults="2"
)

search_google_flights_calendar

获取价格日历，以便灵活规划日期。

参数：

  • flight_type (必需) - "one_way" 或 "round_trip"
  • departure_id (必需) - 机场代码
  • arrival_id (必需) - 机场代码
  • outbound_date (必需) - 参考日期
  • return_date - 往返行程必需

示例：

search_google_flights_calendar(
    flight_type="round_trip",
    departure_id="SFO",
    arrival_id="NYC",
    outbound_date="2025-12-01",
    return_date="2025-12-08"
)

search_google_flights_location_search

搜索机场代码和地点。

参数：

  • q (必需) - 搜索查询（机场名称、城市或代码）
  • gl - 国家代码（默认："us"）
  • hl - 语言代码（默认："en"）

示例：

search_google_flights_location_search(
    q="东京"
)

search_google_travel_explore

探索旅行目的地，寻找灵感。

参数：

  • departure_id (必需) - 出发机场代码或地点
  • arrival_id - 目的地（默认为任何地方）
  • time_period - 旅行期间（例如，“十二月两周的旅行”）
  • interests - 按兴趣筛选："popular", "outdoors", "beaches", "museums", "history", "skiing"
  • travel_class - "economy", "premium_economy", "business", "first_class"
  • adults - 成人人数（默认："1"）
  • currency - 货币代码（默认："USD"）

示例：

search_google_travel_explore(
    departure_id="JFK",
    interests="beaches",
    time_period="two_week_trip_in_december"
)

Google 酒