SerpApi MCP

официальный

Сервер SerpApi MCP для результатов поиска Google и других поисковых систем.

GitHub
184

Что можно делать с SerpApi MCP?

  • Поиск в нескольких системах — Выполняйте поиск в Google, Bing, YouTube, eBay и других системах одним вызовом search, выбирая систему и местоположение.
  • Markdown или компактный вывод — Запрашивайте результаты в формате Markdown или компактного JSON, чтобы сократить расход токенов при больших или вложенных ответах.
  • Извлечение страниц — Используйте extract, чтобы прочитать отдельную страницу, получить карту URL-адресов сайта или просканировать несколько страниц с ограничением их количества.
  • Интерактивное представление результатов — Выберите search_table или search_dashboard, чтобы отображать результаты в виде сортируемой таблицы или панели управления в поддерживающих это хостах.

Документация

SerpApi MCP Server

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

Python 3.13+ MIT License Install in VS Code Install in Cursor

Возможности

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

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

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/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 (или перетащите в Settings → Extensions). Во время установки Claude Desktop запросит API-ключ SerpApi, сохранит его как конфиденциальную настройку и запустит сервер локально через stdio. При установке необходимые Python и зависимости устанавливаются с помощью uv. Один и тот же пакет работает в macOS, Windows и Linux.

Эту же точку входа 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 и инструментов App он необходим; без него возвращается ошибка.

Инструмент 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.

Если ответ добавляет новое обязательное поле, инструмент перечисляет оставшиеся поля, которые агент должен указать в новом вызове. Формы поддерживают строки, числа, логические значения и поля с выбором одного варианта; для неподдерживаемых сложных полей возвращается ошибка об отсутствующем параметре. Неизвестные поисковые системы передаются в SerpApi без изменений.

Инструмент Extract

Инструмент extract читает веб-страницы и возвращает их содержимое в виде структурированного JSON или Markdown. Можно извлечь одну страницу, найти URL-адреса сайта или просканировать несколько страниц. Все доступные параметры приведены в справочнике API Extract или в ресурсе serpapi://engines/extract.

Некоторые доступные параметры:

  • params.url (обязательный): URL страницы или сайта
  • params.mode: режим извлечения; "scrape" (по умолчанию) читает одну страницу, "map" находит URL-адреса, а "crawl" извлекает данные с нескольких страниц
  • params.include_markdown: включить содержимое страницы в формате Markdown; по умолчанию используется true для scrape и crawl или задайте false, чтобы отключить эту функцию
  • params.output: формат ответа; по умолчанию используется "json" в полном режиме и "md" в компактном режиме. Укажите его явно, чтобы переопределить формат.
  • params.max_pages: максимальное количество страниц для сканирования, включая начальную страницу (по умолчанию: 10, максимум: 100)
  • params.json_restrictor: выберите поля для возврата, например "markdown,error"
  • mode: режим ответа; "complete" (по умолчанию) возвращает полный ответ. "compact" по умолчанию возвращает Markdown в исходном формате. При явном указании params.output="json" компактное извлечение одной страницы сохраняет поле верхнего уровня markdown, если оно присутствует, и сохраняет ошибки API. Ответы без Markdown, включая результаты, перенаправленные в другую поисковую систему, сохраняют данные, удаляя метаданные. Явные значения params.json_restrictor и params.include_markdown=false имеют приоритет при использовании JSON. Для map и crawl компактный JSON удаляет метаданные. Вывод Markdown возвращается без изменений.

Примеры:

{"name": "extract", "arguments": {"params": {"url": "https://example.com"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com"}, "mode": "compact"}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "output": "md"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "map"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "crawl", "max_pages": 2}}}

Чтобы получить содержимое одной страницы в исходном формате Markdown, используйте mode="compact". Добавьте params.output="json", чтобы получить JSON с полем markdown. Полный JSON включает это поле по умолчанию; JSON для crawl включает его в каждую запись pages. Если задать params.output="json" и params.include_markdown=false, остальные структурированные поля сохранятся, а Markdown будет исключён.

При сканировании сайта за каждую успешно извлечённую страницу в запросе без кэширования списывается один поисковый кредит. Используйте params.max_pages, чтобы ограничить количество извлекаемых страниц.

Интерактивный интерфейс (MCP apps)

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

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

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

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

  • «Отсутствует 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 или создайте обращение.

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

Инструкции по настройке среды разработки, обновлению схем, тестированию, сборке Docker и пакетов MCP, а также выпуску версий см. в CONTRIBUTING.md.

Лицензия

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