SearchAPI Mcp

SearchAPI MCP 服务

---

功能

🔍 搜索引擎

• Google 搜索 - 网页结果、知识图谱、答案框、相关问题
• Google 视频 - 可按时长、来源和上传时间筛选的视频搜索
• Google AI Mode - 提供带引用来源和结构化内容的 AI 生成概览
• Google 地图 - 地点、商家、评价和位置详情
• Google 地图地点 - 特定地点的详细信息（营业时间、照片、便利设施）
• Google 活动 - 查找音乐会、会议、节日和本地活动
• Google Flights - 支持全面筛选和价格日历的航班搜索
• Google Flights 位置搜索 - 机场代码查询和自动补全
• Google Travel Explore - 发现旅行目的地和灵感
• Google 酒店 - 可按便利设施、评分和价格筛选的住宿搜索

🏗️ 面向生产环境的架构

• 连接池 - 使用 httpx 高效管理 HTTP 连接
• 响应缓存 - 支持配置基于 TTL 的缓存和 LRU 淘汰
• 重试逻辑 - 针对瞬时故障采用指数退避
• 熔断器 - 防止故障级联的故障安全模式
• 指标收集 - 请求数、延迟、缓存命中率、错误跟踪
• 运行状况检查 - 监控 API 连接和服务状态

⚙️ 配置与监控

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

---

快速开始

前提条件

• Python 3.10 或更高版本
• SearchAPI.io API 密钥（在此获取）

使用 UV 安装（推荐）

使用 uvx 是最快的入门方式：

# Set your API key
export SEARCHAPI_API_KEY="your_api_key_here"

# Run directly with uvx (no installation needed)
uvx --from git+https://github.com/RmMargt/searchAPI-mcp.git mcp-server-searchapi

---

安装

方法 1：UV（推荐）

UV 是最快捷、最方便的方法：

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/RmMargt/searchAPI-mcp.git
cd searchAPI-mcp

# Install dependencies
uv pip install -r requirements.txt

方法 2：pip

# Clone the repository
git clone https://github.com/RmMargt/searchAPI-mcp.git
cd searchAPI-mcp

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

方法 3：从源代码安装

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

# Using uv
uv pip install httpx fastmcp python-dotenv pydantic pydantic-settings

# Or using pip
pip install httpx fastmcp python-dotenv pydantic pydantic-settings

---

配置

环境变量

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

# Required
SEARCHAPI_API_KEY=your_api_key_here

# Optional - API Configuration
SEARCHAPI_API_URL=https://www.searchapi.io/api/v1/search
TIMEOUT=30.0
MAX_RETRIES=3
RETRY_BACKOFF=1.0

# Optional - Cache Configuration
ENABLE_CACHE=true
CACHE_TTL=3600
CACHE_MAX_SIZE=1000

# Optional - Connection Pool
POOL_CONNECTIONS=10
POOL_MAXSIZE=10

# Optional - Monitoring
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: Open User Configuration”命令：

{
  "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 编辑器

将以下内容添加到 ~/.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 Servers：

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

通用 MCP 客户端

适用于任何兼容 MCP 的客户端：

# Using stdio transport (default)
python /path/to/searchAPI-mcp/mcp_server_refactored.py

# With environment variable
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）

示例：

# Get today's date in ISO format
get_current_time(format="iso")
# Returns: {"date": "2025-11-16", "now": {...}, "travel_dates": {...}}

# Get date 7 days from now with future dates array
get_current_time(days_offset=7, return_future_dates=True, future_days=30)

---

Google 搜索

search_google

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

参数：

• q（必填）- 搜索查询
• location - 地点名称（例如："New York, NY"）
• 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 programming tutorials",
    location="San Francisco, CA",
    time_period="last_month",
    num="20"
)

search_google_videos

在 Google Videos 中搜索视频内容。

**参数：**与 search_google 类似，另含视频专用筛选条件

• q（必填）- 搜索查询
• time_period - 按上传时间筛选
• device - "desktop" 或 "mobile"

示例：

search_google_videos(
    q="machine learning tutorial",
    time_period="last_week",
    num="10"
)

search_google_ai_mode

通过 AI 生成的概览和引用来源进行搜索。

参数：

• q - 搜索查询（必填，除非提供 url）
• url - 用于搜索的图片 URL
• location - 用于返回本地化结果的地点

返回：

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

示例：

search_google_ai_mode(
    q="How does machine learning work?",
    location="United States"
)

---

Google 地图

search_google_maps

搜索地点、商家和服务。

参数：

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

示例：

search_google_maps(
    query="coffee shops near Central Park",
    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（必填）- 搜索查询（例如："concerts in NYC"、"tech conferences"）
• location - 用于返回本地化结果的地点名称
• chips - 日期筛选（"today"、"tomorrow"、"week"、"weekend"、"month"）或活动类型
• gl - 国家/地区代码（默认值："us"）
• hl - 语言代码（默认值："en"）
• page - 页码（默认值："1"）

示例：

search_google_events(
    q="music festivals in Austin",
    chips="weekend",
    location="Austin, TX"
)

---

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 — round_trip 时必需

示例：

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="Tokyo"
)

search_google_travel_explore

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

参数：

• departure_id（必需）— 出发机场代码或地点
• arrival_id — 目的地（默认值为任意地点）
• time_period — 旅行时间段（例如："two_week_trip_in_december"）
• 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 酒店

search_google_hotels

搜索酒店和住宿。

参数：

• q（必需）— 地点查询
• check_in_date（必需）— 入住日期（YYYY-MM-DD）
• check_out_date（必需）— 退房日期（YYYY-MM-DD）
• adults — 成人数量（默认值："2"）
• rating — 最低评分："3"、"4"、"5"
• hotel_class — 星级："2"-"5"
• price_min / price_max — 价格范围
• amenities — 按设施筛选（例如："pool,wifi,parking"）
• free_cancellation — "true" 或 "false"

示例：

search_google_hotels(
    q="hotels in Paris",
    check_in_date="2025-12-20",
    check_out_date="2025-12-25",
    adults="2",
    rating="4",
    amenities="wifi,pool",
    price_max="300",
    free_cancellation="true"
)

search_google_hotels_property

获取特定酒店的详细信息。

参数：

• property_token（必需）— 搜索结果中的住宿 ID
• check_in_date（必需）— 入住日期
• check_out_date（必需）— 退房日期
• adults — 成人数量

示例：

search_google_hotels_property(
    property_token="ChIJd8BlQ2BZwokRAFUEcm_qrcA",
    check_in_date="2025-12-20",
    check_out_date="2025-12-25",
    adults="2"
)

---

使用示例

示例 1：发现并规划行程

# 1. Explore destinations from New York
destinations = search_google_travel_explore(
    departure_id="JFK",
    interests="beaches",
    time_period="two_week_trip_in_december"
)

# 2. Get current date and travel dates
dates = get_current_time(return_future_dates=True, future_days=30)
check_in = dates["travel_dates"]["next_week"]
check_out = dates["travel_dates"]["next_month"]

# 3. Search for flights
flights = search_google_flights(
    departure_id="JFK",
    arrival_id="CDG",
    outbound_date=check_in,
    return_date=check_out,
    flight_type="round_trip",
    travel_class="economy",
    adults="2"
)

# 4. Search for hotels
hotels = search_google_hotels(
    q="hotels in Paris",
    check_in_date=check_in,
    check_out_date=check_out,
    adults="2",
    rating="4",
    amenities="wifi,breakfast"
)

# 5. Find nearby restaurants
restaurants = search_google_maps(
    query="restaurants near Eiffel Tower"
)

# 6. Get detailed place info
place_details = search_google_maps_place(
    place_id=restaurants["local_results"][0]["place_id"]
)

# 7. Find local events
events = search_google_events(
    q="concerts in Paris",
    chips="weekend"
)

示例 2：使用 AI 模式进行研究

# Get AI-generated overview with sources
result = search_google_ai_mode(
    q="What are the health benefits of Mediterranean diet?",
    location="United States"
)

# Result includes:
# - result["markdown"] - AI overview in markdown format
# - result["text_blocks"] - Structured content blocks
# - result["reference_links"] - Cited sources
# - result["web_results"] - Traditional search results

示例 3：监控服务运行状况

# Check API health and metrics
health = health_check()

print(f"Status: {health['api_status']['status']}")
print(f"Latency: {health['api_status']['latency_ms']}ms")
print(f"Cache hit rate: {health['metrics']['cache_hit_rate']:.2%}")
print(f"Total requests: {health['metrics']['request_count']}")

---

开发

运行测试

# Run all tests
python -m pytest

# Run specific test file
python test_refactored.py

代码结构

searchAPI-mcp/
├── mcp_server_refactored.py  # Main MCP server with FastMCP
├── config.py                  # Configuration with Pydantic validation
├── client.py                  # HTTP client with pooling, retry, caching
├── requirements.txt           # Python dependencies
├── .env.example              # Example environment variables
└── tests/                    # Test files

关键组件

• mcp_server_refactored.py — 使用 FastMCP 实现的 MCP 服务

  • 附带详尽文档字符串的工具定义
  • 健康检查和监控端点
  • 平稳关闭和资源管理

• config.py — 配置管理

  • 使用 Pydantic 模型实现类型安全的配置
  • 环境变量验证
  • 合理的默认值和覆盖选项

• client.py — 可用于生产环境的 HTTP 客户端

  • 使用 httpx 进行连接池管理
  • 指数退避重试逻辑
  • 基于 TTL 的响应缓存
  • 熔断器模式
  • 指标收集

调试

使用 MCP Inspector 测试工具：

# Install inspector
npm install -g @modelcontextprotocol/inspector

# Run inspector
npx @modelcontextprotocol/inspector python mcp_server_refactored.py

设置环境变量以启用详细日志记录：

LOG_LEVEL=DEBUG python mcp_server_refactored.py

---

故障排除

常见问题

问题："Invalid API key" 错误

• 解决方案：确保在环境变量或 .env 文件中正确设置 SEARCHAPI_API_KEY
• 在 https://www.searchapi.io/ 获取 API 密钥

问题："Circuit breaker is OPEN" 错误

• 原因：连续发生过多 API 调用失败
• 解决方案：检查互联网连接和 API 密钥。等待 60 秒，让熔断器重置；或重启服务

问题：连接超时

• 解决方案：在 .env 中增大超时时间：TIMEOUT=60.0
• 检查到 SearchAPI.io 的网络连接

问题：延迟过高

• 解决方案：如果缓存已禁用，请启用缓存：ENABLE_CACHE=true
• 增大缓存容量：CACHE_MAX_SIZE=5000
• 使用 health_check 工具检查指标

问题：Windows 编码错误

• 解决方案：在 MCP 客户端配置中设置环境变量：

  "env": {
    "PYTHONIOENCODING": "utf-8",
    "SEARCHAPI_API_KEY": "your_key"
  }
  

获取帮助

• 查看 MCP 文档
• 阅读 SearchAPI.io 文档
• 在 GitHub 上提交问题

---

性能调优

缓存配置

若要提高缓存命中率：

CACHE_TTL=7200        # 2 hours
CACHE_MAX_SIZE=5000   # Store more results

对于内存受限的环境：

CACHE_TTL=1800        # 30 minutes
CACHE_MAX_SIZE=100    # Smaller cache

连接池

对于高流量场景：

POOL_CONNECTIONS=50
POOL_MAXSIZE=50

对于低流量场景：

POOL_CONNECTIONS=5
POOL_MAXSIZE=5

---

安全注意事项

⚠️ 重要安全提示：

1. API 密钥保护

   • 切勿将 .env 文件提交到版本控制系统
   • 在生产环境中使用环境变量
   • 定期轮换 API 密钥

2. 速率限制

   • SearchAPI.io 会根据你的套餐设置速率限制
   • 内置重试逻辑会遵守速率限制
   • 使用 health_check 工具监控用量

3. 数据隐私

   • 搜索查询会发送到 SearchAPI.io
   • 响应会缓存在本地（可配置）
   • 查看 SearchAPI.io 隐私政策

---

许可证

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

---

致谢

• Model Context Protocol - Anthropic 制定的协议规范
• FastMCP - Python MCP 框架
• SearchAPI.io - 搜索 API 服务提供商
• httpx - 适用于 Python 的现代 HTTP 客户端
• Pydantic - 数据验证框架

---

贡献

欢迎贡献！请随时提交 Pull Request。对于重大变更，请先提交问题，讨论你希望进行的更改。

1. Fork 此代码仓库
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 推送到分支（git push origin feature/AmazingFeature）
5. 提交 Pull Request

---

更新日志

v1.1.0（当前版本）

• ✅ 新增： Google Maps Place API - 详细地点信息
• ✅ 新增： Google Events API - 活动和事件搜索
• ✅ 新增： Google Travel Explore API - 目的地发现
• ✅ 新增： Google Flights Location Search API - 机场查询
• ✅ 增强旅游和旅行研究能力
• ✅ 全面支持旅行规划工作流

v1.0.0

• ✅ 采用 FastMCP 的生产就绪架构
• ✅ 连接池和重试逻辑
• ✅ 带 TTL 的响应缓存
• ✅ 熔断器模式
• ✅ 全面的健康检查和指标
• ✅ Google 搜索、视频、AI Mode
• ✅ Google Maps 和评价
• ✅ Google Flights 和日历
• ✅ Google Hotels 和住宿详情
• ✅ 用于旅行规划的时间工具

---