SerpApi MCP Server

Реализация сервера Model Context Protocol (MCP), который интегрируется с SerpApi для полноформатных результатов поиска и извлечения данных.

Особенности

Поиск по нескольким движкам: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay и ещё
Ресурсы движков: схемы параметров для каждого движка доступны через MCP-ресурсы (см. Инструмент поиска)
Данные погоды в реальном времени: прогнозы по месту через запросы к поиску
Данные фондового рынка: финансовые показатели компаний и рыночные данные через интеграцию с поиском
Динамическая обработка результатов: автоматически распознаёт и форматирует разные типы результатов
Гибкие режимы ответа: полноформатные или компактные JSON-ответы
JSON-ответы: структурированный вывод JSON в полноформатном или компактном режимах
Интерактивный UI (MCP Apps): два опциональных инструмента search_table и search_dashboard, которые отображают результаты как интерактивный UI прямо в поддерживаемых хостах

Быстрый старт

SerpApi MCP Server доступен как размещённый сервис на mcp.serpapi.com. Чтобы подключиться к нему, понадобится API-ключ. Его можно найти на вашей панели SerpApi.

Вы можете настроить Claude Desktop на использование размещённого сервера:

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

Также размещённый сервер можно добавить в эти MCP-клиенты:

OpenClaw

openclaw mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp --transport streamable-http

Claude Code

claude mcp add --transport http serpapi https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp

Hermes

hermes mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp

Codex

codex mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp

Самостоятельный развертывание

git clone https://github.com/serpapi/serpapi-mcp.git
cd serpapi-mcp
uv sync && uv run src/server.py

Настройте Claude Desktop:

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

Получить API-ключ можно на странице: serpapi.com/manage-api-key

Аутентификация

Поддерживаются два метода:

По пути: /YOUR_API_KEY/mcp (рекомендуется)
По заголовку: Authorization: Bearer YOUR_API_KEY

Примеры:

# По пути
curl "https://mcp.serpapi.com/your_key/mcp" -d '...'

# По заголовку
curl "https://mcp.serpapi.com/mcp" -H "Authorization: Bearer your_key" -d '...'

Инструмент поиска

MCP-сервер имеет один основной инструмент Search Tool, который поддерживает все движки SerpApi и типы результатов. Все доступные параметры можно найти в справочнике API SerpApi.

Схемы параметров движков также открыты как MCP-ресурсы: serpapi://engines (index) и serpapi://engines/<engine>.

Параметры, которые можно передать, специфичны для каждого API-движка. Ниже приведены некоторые примеры:

params.q (обязателен): Поисковый запрос
params.engine: Поисковый движок (по умолчанию: "google_light")
params.location: Географический фильтр
mode: Режим вывода — "complete" (по умолчанию) или "compact"
...см. другие параметры в справочнике API SerpApi

Примеры:

{"name": "search", "arguments": {"params": {"q": "coffee shops", "location": "Austin, TX"}}}
{"name": "search", "arguments": {"params": {"q": "weather in London"}}}
{"name": "search", "arguments": {"params": {"q": "AAPL stock"}}}
{"name": "search", "arguments": {"params": {"q": "news"}, "mode": "compact"}}
{"name": "search", "arguments": {"params": {"q": "detailed search"}, "mode": "complete"}}

Поддерживаемые движки: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay и другие (см. serpapi://engines).

Типы результатов: блоки-ответы, органические результаты, новости, изображения, покупки — автоматически обнаруживаются и форматируются.

Интерактивный UI (MCP Apps)

По умолчанию инструмент search возвращает JSON и не изменяется. Для хостов, поддерживающих расширение MCP Apps (SEP-1865), предусмотрены два опциональных инструмента, которые отображают результаты как интерактивный UI прямо в диалоге, чтобы bulk SERP JSON не попадал в контекст модели:

search_table: органические результаты в виде сортируемой, поиск-ориентированной таблицы
search_dashboard: сводные метрики, диаграмма распределения источников и таблица результатов с панелью деталей по клику

Оба инструмента принимают те же параметры params, что и search. Хосты без поддержки MCP Apps просто игнорируют эти инструменты.

Локально можно просмотреть их без MCP-хоста:

uv run fastmcp dev apps src/server.py

Разработка

# Локальная разработка
uv sync && uv run src/server.py

# Docker
docker build -t serpapi-mcp . && docker run -p 8000:8000 serpapi-mcp

# Генерация ресурсов движков (Playground scrape)
python build-engines.py

# Тестирование с MCP Inspector
npx @modelcontextprotocol/inspector
# Настройка: URL mcp.serpapi.com/YOUR_KEY/mcp, Transport "Streamable HTTP transport"

Устранение неполадок

"Missing API key": укажите ключ в URL-пути /{YOUR_KEY}/mcp или в заголовке Bearer YOUR_KEY
"Invalid key": проверьте на serpapi.com/dashboard
"Rate limit exceeded": подождите или обновите план SerpApi
"No results": попробуйте другой запрос или движок

Участие

Fork репозитория
Создайте ветку для фичи: git checkout -b feature/amazing-feature
Установите зависимости: uv install
Внесите изменения
Зафиксируйте изменения: git commit -m 'Add amazing feature'
Отправьте ветку: git push origin feature/amazing-feature
Откройте Pull Request

Лицензия

MIT License - см. файл LICENSE для деталей.