SerpApi MCP

SerpApi MCP Server

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

Возможности

• Поиск по нескольким движкам: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay и другие
• Ресурсы движков: Схемы параметров для каждого движка доступны через ресурсы MCP (см. инструмент поиска)
• Данные о погоде в реальном времени: Погода по местоположению с прогнозами через поисковые запросы
• Данные фондового рынка: Финансовые показатели компаний и рыночные данные через поисковую интеграцию
• Динамическая обработка результатов: Автоматическое определение и форматирование различных типов результатов
• Гибкие режимы ответов: Полные или компактные JSON-ответы
• JSON-ответы (по умолчанию): Структурированный JSON-вывод с полным или компактным режимами
• Markdown-ответы: Сокращение использования токенов в среднем на 50% и более чем на 90% для API со сложным вложенным JSON.
• Интерактивный интерфейс (MCP-приложения): Опциональные инструменты search_table и search_dashboard, которые отображают результаты в виде интерактивного интерфейса в поддерживающих хостах
• Расширение Claude Desktop: Локальная установка в один клик из MCP-пакета (.mcpb), см. ниже

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

SerpApi MCP Server доступен как размещённый сервис на mcp.serpapi.com. Для подключения необходимо предоставить API-ключ. Вы можете найти свой 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/mcp --header "Authorization: Bearer YOUR_SERPAPI_API_KEY"

Hermes

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

Codex (читает ключ из SERPAPI_API_KEY в вашей оболочке)

codex mcp add serpapi --url https://mcp.serpapi.com/mcp --bearer-token-env-var SERPAPI_API_KEY

Самостоятельное размещение

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

Расширение Claude Desktop (MCP-пакет)

Для локальной установки в один клик загрузите пакет .mcpb из последнего релиза (или соберите его, как указано ниже) и откройте его с помощью Claude Desktop (или перетащите в Настройки → Расширения). Claude Desktop запросит ваш API-ключ SerpApi во время установки, сохранит его как конфиденциальную настройку и запустит сервер локально через stdio. Пакет использует среду выполнения MCPB uv: он содержит только исходный код, pyproject.toml и uv.lock, а Claude Desktop предоставляет Python и зафиксированные зависимости с помощью uv во время установки, поэтому ничего не поставляется в комплекте, и один пакет работает на macOS, Windows и Linux.

uv run mcpb/build.py   # needs Node.js for the MCPB CLI; writes dist/serpapi-mcp-<version>.mcpb

Всё, что связано с пакетом, находится в mcpb/, а также .mcpbignore в корне проекта. Сборка перегенерирует схемы движков из SerpApi Playground (--no-rebuild-engines включает engines/ из рабочего дерева вместо этого), проверяет mcpb/manifest.json, упаковывает файлы, отслеживаемые git, за вычетом .mcpbignore, с манифестом в корне пакета, затем устанавливает его во временную директорию и запускает через stdio, чтобы убедиться, что всё работает (--no-smoke пропускает этот последний шаг). Пакет собирается только во время релиза: отправка тега v<version> запускает рабочий процесс релиза, который выполняет набор тестов, а затем развёртывает размещённый сервер, публикует запись в реестре MCP, собирает пакет и прикрепляет его к релизу GitHub. Пулл-реквесты запускают тесты манифеста и точки входа stdio в tests/test_mcpb.py, но не упаковывают пакет.

Та же точка входа stdio работает с любым локальным MCP-хостом, который запускает серверы как подпроцесс:

{
  "mcpServers": {
    "serpapi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/serpapi-mcp", "--frozen", "--no-dev", "src/stdio.py"],
      "env": { "SERPAPI_API_KEY": "YOUR_SERPAPI_API_KEY" }
    }
  }
}

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

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

• На основе заголовка: Authorization: Bearer YOUR_API_KEY (рекомендуется: ключ не попадает в URL и логи)
• На основе пути: /YOUR_API_KEY/mcp, для клиентов, которые не могут устанавливать заголовки

Примеры:

# Header-based
curl "https://mcp.serpapi.com/mcp" -H "Authorization: Bearer your_key" -d '...'

# Path-based
curl "https://mcp.serpapi.com/your_key/mcp" -d '...'

Для подключения, перечисления инструментов или чтения ресурсов ключ не требуется. search и инструменты приложений требуют его и возвращают ошибку без него.

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

MCP-сервер имеет один основной инструмент поиска, который поддерживает все движки и типы результатов SerpApi. Все доступные параметры можно найти в справочнике API SerpApi. Схемы параметров движков также доступны как ресурсы MCP: serpapi://engines (индекс) и serpapi://engines/<engine>. Клиенты, поддерживающие завершение аргументов, могут запрашивать предложения имён движков для serpapi://engines/{engine_name}. Например, префикс google_f предлагает соответствующие идентификаторы движков. Это завершает параметр URI ресурса, а не произвольные поисковые запросы.

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

• params.q (обязательно): Поисковый запрос
• params.engine: Поисковый движок (по умолчанию: "google_light")
• params.location: Географический фильтр
• params.output: Формат ответа; опустите для JSON (по умолчанию) или установите "md" для Markdown
• mode: Режим ответа; "compact" удаляет метаданные из JSON, а Markdown возвращается без изменений
• ...другие параметры см. в справочнике 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"}}
{"name": "search", "arguments": {"params": {"q": "news", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "amazon", "k": "mechanical keyboards", "amazon_domain": "amazon.com", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "google_scholar", "q": "retrieval augmented generation"}}}
{"name": "search", "arguments": {"params": {"engine": "youtube", "search_query": "how to make espresso"}}}
{"name": "search", "arguments": {"params": {"engine": "apple_app_store", "term": "habit tracker"}}}
{"name": "search", "arguments": {"params": {"engine": "ebay", "_nkw": "vintage mechanical keyboard"}}}

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

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

Поисковые ответы сохраняют существующую строку MCP structuredContent.result и включают ту же строку в текстовое содержимое. Для JSON-вывода result содержит сериализованный JSON; существующие клиенты могут продолжать разбирать его с помощью JSON.parse(response.structuredContent.result). Для Markdown-вывода он содержит неизменённый Markdown. Ошибки и отмены используют ту же обёртку. Сбои выполнения поиска устанавливают isError: true; клиенты, использующие высокоуровневый call_tool() от FastMCP, должны обрабатывать ToolError или использовать call_tool_mcp() для проверки флага результата. См. результаты инструментов MCP.

search использует каталог движков и правила, специфичные для движков, для определения отсутствующих параметров. Клиенты, поддерживающие MCP 2026-07-28, получают форму до выполнения любого поиска. Принятые ответы проверяются; отклонение или отмена не выполняют поиск. Устаревшие клиенты и клиенты без запроса формы получают ошибку со списком отсутствующих параметров, чтобы агент мог запросить их в разговоре. См. запросы ввода MCP.

• Google Flights: идентификаторы отправления и прибытия, дата вылета и дата возврата для рейсов туда и обратно. Даты и идентификаторы аэропортов проверяются. Поиск по токенам, маршруты с несколькими городами и selected_flights_json сохраняют существующее поведение.
• Google Hotels: запрос пункта назначения или отеля, дата заезда и дата выезда. Дата выезда должна следовать за датой заезда. Количество гостей и другие необязательные фильтры сохраняют значения вызывающего или значения API по умолчанию.
• Google Maps Directions: отсутствующие адреса отправления и назначения. Координаты или идентификаторы данных мест, уже предоставленные, удовлетворяют соответствующей конечной точке.
• Другие движки каталога используют свои обязательные поля, такие как search_query для YouTube, find_loc для Yelp и k для Amazon. Правила движков учитывают известные значения по умолчанию и альтернативы, включая узлы категорий Amazon, категории eBay и поиск цитирования Google Scholar.

Форма формируется на основе исходных аргументов каждого запроса. Она не использует requestState или локальное хранилище продолжения процесса, поэтому повторная попытка может выполняться на другом реплике без общего ключа защиты состояния. Аутентификация применяется к каждому HTTP-запросу, и используются только ответы на запрошенные поля. Если ответ вводит другое требование, инструмент перечисляет оставшиеся поля для агента, чтобы он указал их в новом вызове.

Чтобы расширить управляемый поиск, добавьте обязательные поля, описания, типы и параметры в файл engines/<engine>.json движка. Добавьте запись EngineInputRules в src/engine_input_rules.py, когда требования зависят от других параметров, значений по умолчанию или альтернатив. Общий обработчик MCP в src/search_input.py не требует веток, специфичных для движков. Формы поддерживают строки, числа, логические значения и поля с одним выбором; неподдерживаемые сложные поля получают ошибку отсутствующего параметра. Неизвестные движки передаются в SerpApi.

Интерактивный интерфейс (MCP-приложения)

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

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

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

Предварительный просмотр локально без MCP-хоста:

uv run fastmcp dev apps src/server.py

Разработка

# Local development
uv sync && uv run src/server.py

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

# Build the Claude Desktop extension (MCP Bundle); rebuilds engines, needs Node.js for the MCPB CLI
uv run mcpb/build.py

# Release: update pyproject.toml, server.json, mcpb/manifest.json and uv.lock together.
uv run --no-sync scripts/bump_version.py 2.0.0
# Review and commit the changes before tagging the release.
# Nothing ships on a plain push to main. The tag runs the release workflow, which runs the test
# suite and then deploys the hosted server, publishes server.json to the MCP Registry, and builds
# the MCP Bundle and attaches it to the GitHub release.
git tag v2.0.0 && git push origin v2.0.0

# Regenerate engine resources (Playground scrape)
python build-engines.py

# Testing with MCP Inspector
npx @modelcontextprotocol/inspector
# Configure: URL mcp.serpapi.com/YOUR_KEY/mcp, Transport "Streamable HTTP transport"

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

• "Отсутствует API-ключ": Включите ключ в путь URL /{YOUR_KEY}/mcp или заголовок Bearer YOUR_KEY
• "Недействительный ключ": Проверьте на serpapi.com/dashboard
• "Превышен лимит запросов": Подождите или обновите свой план SerpApi
• "Нет результатов": Попробуйте другой запрос или движок

Политика конфиденциальности

• Отправляется: только параметры, которые MCP-хост передаёт в вызов инструмента. Сервер никогда не видит остальную часть разговора, файлы, память или историю на хосте.
• Пересылается: каждый поиск отправляется на serpapi.com с вашим API-ключом; результаты возвращаются без изменений. См. Политику конфиденциальности SerpApi о том, как SerpApi обрабатывает поиски и учётные записи.
• Сохраняется: mcp.serpapi.com записывает метрики запросов (метод, код состояния, длительность) и не хранит запросы или результаты. Ключ в пути URL может появиться в журналах запросов, поэтому предпочтительнее использовать заголовок.
• Локальный пакет: расширение Claude Desktop работает на вашем компьютере, хранит ключ в настройках Claude Desktop и вызывает serpapi.com напрямую. Ничто не проходит через mcp.serpapi.com.
• Контакт: privacy@serpapi.com или откройте issue.

Участие в разработке

1. Сделайте форк репозитория
2. Создайте свою ветку функций: git checkout -b feature/amazing-feature
3. Установите зависимости: uv install
4. Внесите свои изменения
5. Зафиксируйте изменения: git commit -m 'Add amazing feature'
6. Отправьте в ветку: git push origin feature/amazing-feature
7. Откройте пул-реквест

Лицензия

Лицензия MIT — см. файл LICENSE для подробностей.