Firecrawl MCP

Firecrawl MCP Server

Сервер Model Context Protocol (MCP), который привносит Firecrawl — контекстный API для ИИ-агентов — в клиенты, совместимые с MCP: поиск, скрейпинг и взаимодействие с живым вебом с получением чистого Markdown или структурированных данных.

Огромная благодарность @vrknetha и @knacklabs за первоначальную реализацию!

Возможности

• Поиск в вебе, при необходимости с полным содержимым страницы для каждого результата
• Поиск по индексам источников для разработчиков (issues на GitHub, смерженные pull request'ы, README и документация), источников правительства США и научных статей (PubMed, bioRxiv, medRxiv, arXiv)
• Скрейпинг любого URL в чистый Markdown или структурированный JSON
• Разбор PDF и документов
• Обход сайта для получения содержимого множества страниц или построение карты для обнаружения его URL
• Взаимодействие со страницами в реальном браузере: клики, ввод текста, заполнение форм и навигация по динамическим страницам
• Запуск задач Agent для многоисточниковых исследований, возвращающих структурированные данные
• Мониторинг страниц и уведомления при изменении их содержимого
• Проверка текущего и исторического расхода кредитов Firecrawl
• Автоматические повторные попытки и ограничение частоты запросов
• Поддержка облака и самостоятельного размещения
• Поддержка SSE

Попробуйте наш MCP Server на площадке MCP.so или на Klavis AI.

Когда использовать этот сервер

• Используйте firecrawl_scrape, когда у вас есть известный URL и вы хотите получить его содержимое в виде markdown или JSON, соответствующего предоставленной вами схеме.
• Используйте firecrawl_map, когда нужно обнаружить URL на сайте, не загружая их содержимое.
• Используйте firecrawl_crawl, когда нужно содержимое множества страниц в пределах сайта; задайте limit, includePaths/excludePaths или maxDiscoveryDepth, чтобы ограничить его.
• Используйте firecrawl_search, когда вы начинаете с запроса, а не с URL, и хотите получить ранжированные результаты веб-поиска. Результаты содержат выдержки; загружайте полные страницы с помощью firecrawl_scrape по нужным URL. scrapeOptions загружает страницу каждого результата в том же вызове и тарифицирует каждый как скрейпинг, поэтому используйте его для полного текста нескольких результатов (эндпоинт только поиска никогда не загружает содержимое).
• Используйте firecrawl_interact, когда странице требуется действие клика, ввода или навигации, прежде чем вы сможете её прочитать: передайте url для новой страницы или scrapeId, чтобы продолжить на уже скрейпленной.
• Используйте инструменты firecrawl_monitor_*, когда одну и ту же страницу нужно проверять по повторяющемуся расписанию с диффами и оповещениями об изменениях, а не загружать один раз.
• Используйте firecrawl_credit_usage, чтобы проверить оставшиеся кредиты или на что они были потрачены, по месяцам или дням, при необходимости с разбивкой по эндпоинту или API-ключу.
• Рассмотрите другой вариант, когда вам нужно удерживать сессию браузера открытой на протяжении множества ваших собственных шагов с вашей собственной логикой повторных попыток и завершения: каждый вызов firecrawl_interact выполняет один ход prompt или code до завершения и возвращает управление. Сессия может сохраняться между вызовами через scrapeId и завершается с помощью firecrawl_interact_stop, но вы не можете управлять ею интерактивно шаг за шагом со стороны клиента в рамках одного вызова.

Этот сервер предоставляет 27 инструментов, когда полный профиль регистрируется с настройками по умолчанию (включая инструменты обратной связи, не в режиме локального запуска без ключа). Установка FIRECRAWL_NO_SEARCH_FEEDBACK=1 и/или FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 удаляет соответствующие инструменты обратной связи и уменьшает это число, как и локальный запуск без ключа. Для клиентов с ограничением на количество инструментов: размещённый эндпоинт без ключа (https://mcp.firecrawl.dev/v2/mcp, без API-ключа) предоставляет только 3 (firecrawl_scrape, firecrawl_search, firecrawl_parse), а выделенный эндпоинт только поиска (https://mcp.firecrawl.dev/v2/mcp-search) предоставляет фиксированный набор из 9 инструментов (поиск по разработчикам, правительственным источникам и научным статьям, а также поиск и выполнение в каталоге Alexandria).

Установка

Размещённый MCP (бесплатный уровень без ключа)

Подключитесь к удалённому размещённому серверу без какой-либо настройки:

https://mcp.firecrawl.dev/v2/mcp

На бесплатном уровне без ключа scrape, search и parse работают без API-ключа (с ограничением частоты). Другие инструменты, такие как crawl, map и agent, по-прежнему требуют ключ.

Предпочитайте OAuth или API-ключ всякий раз, когда человек может зарегистрироваться. Это открывает полный набор инструментов и более высокие лимиты.

Для интерактивного подключения аккаунта настройте ваш MCP-клиент на использование этого URL сервера. Это MCP-эндпоинт, а не страница браузера; используйте процедуру подключения аккаунта в клиенте и не добавляйте вторую запись сервера Firecrawl при переподключении:

https://mcp.firecrawl.dev/v2/mcp-oauth

Для подключения по API-ключу (например, для необслуживаемой интеграции) оставьте URL сервера таким:

https://mcp.firecrawl.dev/v2/mcp

Затем настройте защищённый заголовок или секретную настройку клиента с помощью:

Authorization: Bearer <FIRECRAWL_API_KEY>

Никогда не помещайте API-ключ в URL сервера. Никогда не помещайте API-ключ в чат агента. Настраивайте его напрямую в клиенте или менеджере секретов. См. руководство по настройке размещённого MCP и руководство по подключению агента для инструкций по конкретным клиентам.

Именование вашей интеграции

Интеграция, подключающаяся по HTTP, может назвать себя с помощью заголовка X-Firecrawl-Origin, например X-Firecrawl-Origin: my-agent. Сервер сообщает его Firecrawl как источник запроса mcp-my-agent@<server version> вместо имени клиента или User-Agent, которые он сообщал бы иначе. Используйте буквы, цифры и дефисы: каждая последовательность других символов превращается в один дефис, ведущие и завершающие дефисы отбрасываются, а имя обрезается до 48 символов. На результаты инструментов это не влияет; меняется только источник, отправляемый в Firecrawl API (и передаваемый в beforeKeylessRequest эмбеддера).

Эндпоинт только поиска

Поверхность поиска с фиксированной областью также размещена по адресу:

https://mcp.firecrawl.dev/v2/mcp-search

Он предоставляет фиксированный набор из девяти инструментов: firecrawl_search, firecrawl_developer_search, firecrawl_gov_search, четыре инструмента firecrawl_research_* и два инструмента Alexandria firecrawl_find_tools и firecrawl_scrape. Его firecrawl_search не загружает содержимое страниц.

Запуск через npx

env FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp

Ручная установка

npm install -g firecrawl-mcp

Запуск в Cursor

Настройка Cursor 🖥️ Примечание: требуется Cursor версии 0.45.6+ Для получения самых актуальных инструкций по настройке обратитесь к официальной документации Cursor по настройке MCP-серверов: Руководство по настройке MCP Server в Cursor

Чтобы настроить Firecrawl MCP в Cursor v0.48.6

1. Откройте настройки Cursor
2. Перейдите в Features > MCP Servers
3. Нажмите "+ Add new global MCP server"
4. Введите следующий код:

   {
     "mcpServers": {
       "firecrawl-mcp": {
         "command": "npx",
         "args": ["-y", "firecrawl-mcp"],
         "env": {
           "FIRECRAWL_API_KEY": "YOUR-API-KEY"
         }
       }
     }
   }
   

Чтобы настроить Firecrawl MCP в Cursor v0.45.6

1. Откройте настройки Cursor
2. Перейдите в Features > MCP Servers
3. Нажмите "+ Add New MCP Server"
4. Введите следующее:
   • Name: "firecrawl-mcp" (или предпочитаемое вами имя)
   • Type: "command"
   • Command: env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp

Если вы используете Windows и столкнулись с проблемами, попробуйте cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"

Замените your-api-key на ваш API-ключ Firecrawl. Если у вас его ещё нет, вы можете создать аккаунт и получить его на https://www.firecrawl.dev/app/api-keys

После добавления обновите список MCP-серверов, чтобы увидеть новые инструменты. Composer Agent будет автоматически использовать Firecrawl MCP, когда это уместно, но вы можете явно запросить его, описав, что вам нужно из веба. Откройте Composer через Command+L (Mac), выберите "Agent" рядом с кнопкой отправки и введите ваш запрос.

Запуск в Windsurf

Добавьте это в ваш ./codeium/windsurf/model_config.json:

{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Запуск в локальном режиме Streamable HTTP

Чтобы запустить сервер с использованием Streamable HTTP локально вместо транспорта stdio по умолчанию:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp

Используйте url: http://localhost:3000/mcp

В этом режиме сервер отвечает только на запросы, адресованные localhost, 127.0.0.1 или [::1] (на любом порту), а также на адрес в HOST, когда он не равен 0.0.0.0 или ::. Запрос, чей заголовок Host указывает другой хост, или чей заголовок Origin указывает другой сайт, получает 403, а заголовки CORS возвращают разрешённый источник вместо *. Запросы GET и HEAD к /health обрабатываются независимо от хоста, поэтому проверки работоспособности продолжают работать, а сервер записывает в лог строку с указанием FIRECRAWL_MCP_ALLOWED_HOSTS для каждого отклонённого запроса. Это не позволяет посещаемым вами веб-страницам вызывать локальный сервер через DNS rebinding или кросс-доменные запросы и использовать его FIRECRAWL_API_KEY.

Чтобы обращаться к серверу под другим именем или адресом, например через имя хоста за обратным прокси или LAN IP, перечислите его в FIRECRAWL_MCP_ALLOWED_HOSTS (через запятую; порты игнорируются). Тот же список определяет, какие браузерные источники могут вызывать сервер. Обратный прокси на той же машине может сохранить адрес привязки по умолчанию:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
  FIRECRAWL_MCP_ALLOWED_HOSTS=mcp.home.lan npx -y firecrawl-mcp

Клиентам на других машинах также нужно, чтобы сервер слушал не на loopback-адресе, поэтому задайте ещё и HOST. Тогда каждый клиент, который может достичь порта, обслуживается с FIRECRAWL_API_KEY сервера, поэтому делайте это только в доверенной сети:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY HOST=0.0.0.0 \
  FIRECRAWL_MCP_ALLOWED_HOSTS=192.168.1.20 npx -y firecrawl-mcp

FIRECRAWL_MCP_ALLOWED_HOSTS=* отключает проверку и восстанавливает wildcard-заголовок CORS. Делайте это только тогда, когда что-то перед сервером само проверяет хосты и источники.

Запуск с Docker

Образ ghcr.io/firecrawl/firecrawl-mcp-server запускает тот же сервер, что и npx -y firecrawl-mcp. Каждая сборка из main помечается тегами latest, v<package version> и sha-<commit sha>. v<package version> указывает на новейшую сборку этой версии, поэтому закрепляйте sha-<commit sha> (или дайджест), когда вам нужен фиксированный образ.

stdio (по умолчанию), для MCP-клиентов, которые запускают сервер как команду:

docker run -i --rm -e FIRECRAWL_API_KEY=fc-YOUR_API_KEY ghcr.io/firecrawl/firecrawl-mcp-server:latest

{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "FIRECRAWL_API_KEY", "ghcr.io/firecrawl/firecrawl-mcp-server:latest"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Streamable HTTP, обслуживаемый по адресу http://localhost:3000/mcp:

docker run --rm -p 127.0.0.1:3000:3000 \
  -e HTTP_STREAMABLE_SERVER=true \
  -e FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
  ghcr.io/firecrawl/firecrawl-mcp-server:latest

Образ задаёт HOST=0.0.0.0 и PORT=3000; переопределите PORT (и сопоставление -p), чтобы слушать в другом месте. Сервер использует FIRECRAWL_API_KEY контейнера для запросов, которые не отправляют собственные учётные данные, поэтому в примере порт публикуется только на 127.0.0.1; не открывайте его шире, если только клиенты не должны предоставлять собственный ключ. Задайте FIRECRAWL_API_URL, чтобы использовать самостоятельно размещённый Firecrawl API. Контейнер работает под непривилегированным пользователем node. Сервер отвечает только на localhost, 127.0.0.1 и [::1] в заголовках Host и Origin, поэтому сопоставление -p 127.0.0.1:3000:3000 работает как есть; чтобы обращаться к нему под другим именем, задайте -e FIRECRAWL_MCP_ALLOWED_HOSTS=<host> (см. Локальный режим Streamable HTTP).

Запуск в VS Code

Для установки в один клик нажмите одну из кнопок установки ниже...

Для ручной установки добавьте следующий JSON-блок в файл User Settings (JSON) в VS Code. Это можно сделать, нажав Ctrl + Shift + P и введя Preferences: Open User Settings (JSON).

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "Firecrawl API Key",
        "password": true
      }
    ],
    "servers": {
      "firecrawl": {
        "command": "npx",
        "args": ["-y", "firecrawl-mcp"],
        "env": {
          "FIRECRAWL_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

При желании вы можете добавить его в файл с именем .vscode/mcp.json в вашем рабочем пространстве. Это позволит вам делиться конфигурацией с другими:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Firecrawl API Key",
      "password": true
    }
  ],
  "servers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "${input:apiKey}"
      }
    }
  }
}

Конфигурация

Переменные окружения

Обязательные для Cloud API

• FIRECRAWL_API_KEY: ваш API-ключ Firecrawl
  • Обязателен при использовании облачного API (по умолчанию)
  • Необязателен при использовании самостоятельно размещённого экземпляра с FIRECRAWL_API_URL
• FIRECRAWL_API_URL (необязательно): пользовательский эндпоинт API для самостоятельно размещённых экземпляров
  • Пример: https://firecrawl.your-domain.com
  • Если не указан, будет использоваться облачный API (требуется API-ключ)
• FIRECRAWL_INTEGRATION (необязательно): тег интеграции для приложений, запускающих этот сервер, например расширения редактора
  • Отправляется как поле integration запросов scrape, batch scrape, crawl, map, search, extract, agent, parse, interact и feedback
  • Используйте значение, начинающееся с _, например _zed

Локальный режим HTTP

• FIRECRAWL_MCP_ALLOWED_HOSTS (необязательно): дополнительные имена хостов или адреса, на которые сервер отвечает с помощью HTTP_STREAMABLE_SERVER=true или SSE_LOCAL=true, через запятую
  • localhost, 127.0.0.1, [::1] и не-wildcard HOST всегда разрешены; порты игнорируются
  • Запросы, в заголовке Host или Origin которых указан любой другой хост, получают 403, кроме запросов GET и HEAD к /health
  • * отключает проверку; не используется с CLOUD_SERVICE=true, который отвечает любому хосту

MCP OAuth (Bearer-токены доступа)

Firecrawl выдаёт OAuth токены доступа (fco_…) через сервер авторизации на firecrawl.dev. Этот MCP-сервер передаёт в Firecrawl API в качестве Authorization: Bearer … те учётные данные, которые он разрешает.

• HTTP-потоковые транспорты (CLOUD_SERVICE=true, HTTP_STREAMABLE_SERVER=true или SSE_LOCAL=true): клиенты должны отправлять Authorization: Bearer <fco_access_token> в MCP-запросах. OAuth bearer-токен имеет приоритет над x-firecrawl-api-key / x-api-key, если присутствуют оба.
• stdio: используйте FIRECRAWL_OAUTH_TOKEN для статического токена доступа или продолжайте использовать FIRECRAWL_API_KEY для API-ключа.

Используйте только токены доступа (fco_…). Токены обновления (fcr_…) должны обмениваться на конечной точке токенов, а не передаваться в API scrape/search.

CLOUD_SERVICE=true

CLOUD_SERVICE=true предоставляет инструменты по streamable HTTP на PORT (по умолчанию 3000, привязан к 0.0.0.0) с более строгими настройками по умолчанию: каждый запрос должен нести учётные данные (API-ключ или OAuth-токен доступа), scrape работает только на чтение (см. инструмент scrape ниже), а firecrawl_parse принимает только загрузки.

FASTMCP_ENDPOINT выбирает набор инструментов: /v2/mcp (по умолчанию) для полного набора инструментов, /v2/mcp-oauth для набора учётной записи или /v2/mcp-search для инструментов только поиска (это также требует FIRECRAWL_MCP_SEARCH_OAUTH_ONLY=true). При полном наборе экземпляр только для поиска также запускается на порту 3001; установите FIRECRAWL_MCP_SEARCH_ENABLED=false, чтобы отключить его.

Примеры конфигурации

Для использования облачного API:

export FIRECRAWL_API_KEY=your-api-key

Для самостоятельно размещённого экземпляра:

# Required for self-hosted
export FIRECRAWL_API_URL=https://firecrawl.your-domain.com

# Optional authentication for self-hosted
export FIRECRAWL_API_KEY=your-api-key  # If your instance requires auth

Использование с Claude Desktop

Добавьте это в ваш claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Как выбрать инструмент

Используйте это руководство, чтобы выбрать подходящий инструмент для вашей задачи:

• Если вы знаете точный URL, который вам нужен: используйте scrape (с форматом JSON для структурированных данных)
• Если у вас несколько известных URL: вызывайте scrape для каждого URL. Если вам нужна именно одна массовая операция API, используйте пакетную конечную точку Firecrawl API вне MCP.
• Если вам нужно обнаружить URL на сайте: используйте map
• Если вы хотите искать информацию в интернете: используйте search
• Если у вас вопрос по программированию (библиотека, контракт API, сообщение об ошибке, известный баг): используйте developer search
• Если у вас юридический или нормативный вопрос (закон, регламент, кодекс, судебное решение или иная публикация правительства США): используйте Firecrawl Government Index
• Если вам нужны научные статьи (биомедицинская, естественнонаучная, клиническая литература или arXiv): используйте research tools, которые ищут по аннотациям и полному тексту статей. search с categories: ["research"] — это другое: фильтр по сайтам поверх обычных веб-результатов.
• Если вам нужно многоисточниковое исследование, возвращающее структурированные данные, вы не знаете URL или ответ охватывает несколько сайтов (сущность и её поля, список, набор данных): используйте agent
• Если вы хотите проанализировать весь сайт или раздел: используйте crawl (с ограничениями!)
• Если вам нужна интерактивная автоматизация браузера (клики, ввод, навигация): используйте interact с URL для новой страницы или scrape + interact, когда вы уже спарсили страницу или нужен более точный контроль над scrape
• Если вам нужны данные от каталогизированного провайдера (Alexandria): выполните поиск с sources: ["alexandria"], изучите выбранный контракт с помощью find_tools и выполните его с помощью scrape alexandria

Таблица быстрого справочника

Инструмент	Лучше всего подходит для	Возвращает
scrape	Содержимое одной страницы	JSON (предпочтительно) или markdown
interact	Взаимодействие с URL или спарсенной страницей	Результат выполнения + scrapeId для режима URL
map	Обнаружение URL на сайте	URL[]
crawl	Извлечение с нескольких страниц (с ограничениями)	итоговый статус/данные crawl после внутреннего опроса
parse	Файлы и ссылки на размещённые загрузки	markdown, JSON или вывод документа
search	Веб-поиск информации	results[]
find_tools	Просмотр каталога Alexandria и поиск URL	провайдеры, контракты инструментов и навигация nextTool
developer	Вопросы по программированию по источникам для разработчиков	results[] с фрагментами
gov	Первичное право и нормативные материалы США	results[] с выдержками
agent	Многоисточниковое исследование, неизвестные или многие сайты	JSON (структурированные данные)
monitor	Регулярные проверки страниц	метаданные и различия monitor/check
research	Исследование статей и репозиториев GitHub	результаты исследования и совпадения репозиториев

Руководство по выбору формата

При использовании scrape выбирайте правильный формат:

• Формат JSON (рекомендуется в большинстве случаев): используйте, когда вам нужны конкретные данные со страницы. Определите схему на основе того, что вам нужно извлечь. Это делает ответы компактными и предотвращает переполнение контекстного окна.
• Формат Markdown (используйте умеренно): только когда вам действительно нужно полное содержимое страницы, например для чтения всей статьи для резюмирования или анализа структуры страницы.

Доступные инструменты

1. Инструмент Scrape (firecrawl_scrape)

Извлекает содержимое с одного URL с расширенными параметрами.

Лучше всего подходит для:

• Извлечения содержимого одной страницы, когда вы точно знаете, какая страница содержит информацию.

Не рекомендуется для:

• Извлечения содержимого с нескольких страниц (используйте повторные вызовы scrape для известных URL, или map + scrape для предварительного обнаружения URL, или crawl для полного содержимого страниц)
• Когда вы не уверены, какая страница содержит информацию (используйте search)

Частые ошибки:

• Передача списка URL в один вызов scrape. В MCP вызывайте scrape один раз на каждый URL. Если вам нужна именно одна массовая операция API, используйте пакетную конечную точку Firecrawl API вне MCP.
• Использование формата markdown по умолчанию (используйте формат JSON, чтобы извлекать только нужное).

Выбор правильного формата:

• Формат JSON (предпочтительно): для большинства случаев используйте формат JSON со схемой, чтобы извлекать только нужные данные. Это делает ответы сфокусированными и предотвращает переполнение контекстного окна.
• Формат Markdown: только когда задача действительно требует полного содержимого страницы (например, резюмирование всей статьи, анализ структуры страницы).

Пример запроса:

"Получи детали продукта с https://example.com/product."

Пример использования (формат JSON — предпочтительно):

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/product",
    "formats": [
      {
        "type": "json",
        "prompt": "Extract the product information",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "price": { "type": "number" },
            "description": { "type": "string" }
          },
          "required": ["name", "price"]
        }
      }
    ]
  }
}

Пример использования (формат markdown — когда нужно полное содержимое):

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/article",
    "formats": ["markdown"],
    "onlyMainContent": true
  }
}

Пример использования (формат branding — извлечение фирменного стиля):

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com",
    "formats": ["branding"]
  }
}

Формат branding: извлекает комплексную фирменную идентичность (цвета, шрифты, типографику, отступы, логотип, UI-компоненты) для анализа дизайна или воспроизведения стиля. Конфиденциальность: установите redactPII: true, чтобы возвращать содержимое с отредактированной персонально идентифицируемой информацией. С CLOUD_SERVICE=true: scrape работает только на чтение. Он не принимает браузерный actions и не может принимать условия провайдера. Указанный profile загружает сохранённое состояние браузера без сохранения изменений в него, а firecrawl_search полной конечной точки обрабатывает scrapeOptions.profile так же. Чтобы сохранить состояние браузера в профиль, откройте страницу с помощью firecrawl_interact (см. ниже). Администратор организации принимает условия в панели управления.

Возвращает:

• Структурированные данные JSON, markdown, профиль branding или другие форматы, как указано.

2. Инструмент Map (firecrawl_map)

Строит карту сайта для обнаружения всех проиндексированных URL на сайте.

Лучше всего подходит для:

• Обнаружения URL на сайте перед тем, как решить, что парсить
• Поиска конкретных разделов сайта

Не рекомендуется для:

• Когда вы уже знаете, какой конкретный URL вам нужен (используйте scrape)
• Когда вам нужно содержимое страниц (используйте scrape после построения карты)

Частые ошибки:

• Использование crawl для обнаружения URL вместо map

Пример запроса:

"Перечисли все URL на example.com."

Пример использования:

{
  "name": "firecrawl_map",
  "arguments": {
    "url": "https://example.com"
  }
}

Возвращает:

• Массив URL, найденных на сайте

3. Инструмент Search (firecrawl_search)

Ищет в интернете и при необходимости извлекает содержимое из результатов поиска.

Лучше всего подходит для:

• Поиска конкретной информации по нескольким сайтам, когда вы не знаете, на каком сайте есть информация.
• Когда вам нужно наиболее релевантное содержимое для запроса

Не рекомендуется для:

• Когда вы уже знаете, какой сайт парсить (используйте scrape)
• Когда вам нужно полное покрытие одного сайта (используйте map или crawl)

Частые ошибки:

• Использование crawl или map для открытых вопросов (используйте вместо этого search)

Пример использования:

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "remote work stipend policies at tech companies",
    "highlights": true,
    "limit": 5,
    "lang": "en",
    "country": "us"
  }
}

Чтобы получить полный текст нескольких результатов в том же вызове, добавьте "scrapeOptions": { "formats": ["markdown"], "onlyMainContent": true }. Каждый извлечённый результат тарифицируется как scrape, поэтому для большинства вопросов используйте выдержки и firecrawl_scrape только нужные вам URL.

Установите highlights в true, чтобы запросить релевантные запросу выделения, или в false, чтобы сохранить исходные фрагменты поиска. Опустите его, чтобы использовать поведение API по умолчанию.

Добавьте "sources": ["alexandria"] для семантического обнаружения инструментов в data.tools, при необходимости в сочетании с web/news/images. Запрос обязателен. Используйте firecrawl_find_tools для контекстного поиска и постепенного раскрытия; см. Alexandria Tools.

О научных статьях см. Research Tools: они ищут по аннотациям и полному тексту статей, а categories: ["research"] здесь фильтрует обычные веб-результаты до сайтов, связанных с исследованиями.

Возвращает:

• Результаты поиска, сгруппированные по источнику (data.web, data.images, data.news), с необязательным извлечённым содержимым, плюс поле id. Каждый результат несёт source и индексированный с 1 position, нумеруемый с 1 внутри своей группы — копируйте пару прямо в valuableResults параметра firecrawl_search_feedback, а не считайте элементы массива. Передайте этот id в firecrawl_search_feedback после того, как вы использовали результаты, чтобы вернуть 1 кредит (поиск стоит 2) и улучшить качество поиска.

Пример запроса:

"Сравни политики компенсации за удалённую работу в технологических компаниях."

3b. Инструмент обратной связи по поиску (firecrawl_search_feedback)

Отправляет структурированную обратную связь по предыдущему результату firecrawl_search. Первая обратная связь для каждого id поиска возвращает 1 кредит и улучшает качество поиска Firecrawl. Идемпотентно для каждого id поиска.

Вызывайте это после каждого поиска, который вы действительно используете (или который не помог). Плохая/частичная обратная связь с missingContent так же ценна, как и хорошая.

Отказ: установите FIRECRAWL_NO_SEARCH_FEEDBACK=1 (или FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1) в окружении при запуске MCP-сервера. Инструмент firecrawl_search_feedback не будет зарегистрирован, поэтому агенты не смогут его вызвать. Администраторы команды также могут отключить обратную связь на стороне сервера; в этом случае инструмент регистрируется, но всегда возвращает feedbackErrorCode: "TEAM_OPTED_OUT". Самое важное поле: missingContent. Это массив конкретных фрагментов контента, которые агент ожидал найти, но не нашёл. Одна запись на каждую отсутствующую тему; они агрегируются по командам и показывают, что индексировать дальше. Для полезных результатов используйте valuableResults с парой source/position, проставленной на каждом результате — результаты группируются, и каждая группа нумеруется с 1 независимо, поэтому нужны оба. Перечислите каждый полезный результат (неперечисленные результаты считаются неполезными), а valuableSources оставьте для полезных URL, которых не было среди возвращённых результатов.

Дневной лимит возвратов (на команду, на календарный день UTC, по умолчанию 100 кредитов). Как только creditsRefundedToday команды достигает dailyRefundCap, дальнейшие отправки по-прежнему записывают отзыв, но больше не возвращают кредиты. В ответе устанавливается dailyCapReached: true. Увидев этот флаг, агенты должны прекратить вызовы этого инструмента до конца календарного дня UTC.

Пример использования:

{
  "name": "firecrawl_search_feedback",
  "arguments": {
    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "good",
    "valuableResults": [
      { "source": "web", "position": 1 },
      { "source": "web", "position": 3 },
      { "source": "news", "position": 2, "reason": "Broke the pricing change." }
    ],
    "valuableSources": [
      {
        "url": "https://docs.firecrawl.dev/pricing",
        "reason": "Not in the results; found via a result's pricing link. Answered the question."
      }
    ],
    "missingContent": [
      {
        "topic": "Pricing for the search endpoint",
        "description": "No pricing tier table for /search specifically."
      },
      { "topic": "Per-team rate limits" }
    ],
    "querySuggestions": "Boost docs.firecrawl.dev for queries that mention 'firecrawl'"
  }
}

Возвращает:

• JSON { success, feedbackId, creditsRefunded, alreadySubmitted? }.

3c. Универсальный инструмент обратной связи (firecrawl_feedback)

Отправляет структурированную обратную связь по завершённой задаче эндпоинта v2 через /v2/feedback. Используйте это для обратной связи на уровне эндпоинта по задачам scrape, parse, map или search. Для качества результатов поиска в частности предпочитайте firecrawl_search_feedback, поскольку он включает рекомендации, специфичные для поиска.

Держите обратную связь краткой: используйте коды проблем, теги, короткие заметки, URL, номера страниц и небольшие объекты метаданных. Не включайте необработанные результаты скрейпинга/парсинга.

Отказ: установите FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 (или FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1) в окружении при запуске MCP-сервера. Инструмент firecrawl_feedback не будет зарегистрирован, поэтому агенты не смогут его вызвать.

Пример использования:

{
  "name": "firecrawl_feedback",
  "arguments": {
    "endpoint": "scrape",
    "jobId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "partial",
    "issues": ["missing_markdown"],
    "tags": ["docs"],
    "note": "The pricing table was missing from the markdown output.",
    "url": "https://example.com/pricing",
    "pageNumbers": [1],
    "metadata": {
      "format": "markdown"
    }
  }
}

Возвращает:

• JSON { success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, websiteCapReached?, alreadySubmitted?, warning? }.

4. Инструмент обхода (firecrawl_crawl)

Запускает задачу обхода, опрашивает до достижения терминального состояния и возвращает финальный статус/данные обхода.

Лучше всего подходит для:

• Извлечения контента с нескольких связанных страниц, когда нужно полное покрытие.

Не рекомендуется для:

• Извлечения контента с одной страницы (используйте scrape)
• Ситуаций, когда важны ограничения по токенам (используйте map + scrape для более точного контроля)
• Ситуаций, когда нужны быстрые результаты (обход может быть медленным)

Предупреждение: ответы обхода могут быть очень большими и превышать лимиты токенов. Ограничьте глубину обхода и количество страниц или используйте map + scrape для более точного контроля.

Частые ошибки:

• Слишком высокие значения limit или maxDiscoveryDepth (вызывают переполнение токенов)
• Использование crawl для одной страницы (используйте scrape)

Пример запроса:

"Получи все посты блога с первых двух уровней example.com/blog."

Пример использования:

{
  "name": "firecrawl_crawl",
  "arguments": {
    "url": "https://example.com/blog/*",
    "maxDiscoveryDepth": 2,
    "limit": 100,
    "allowExternalLinks": false,
    "deduplicateSimilarURLs": true
  }
}

Возвращает:

• Финальный статус и данные обхода после внутреннего опроса, включая id, status, completed, total, creditsUsed, expiresAt, next и data. Используйте возвращённый id с firecrawl_check_crawl_status, если позже понадобится повторно проверить задачу.

5. Проверка статуса обхода (firecrawl_check_crawl_status)

Проверяет статус и результаты существующей задачи обхода по ID.

{
  "name": "firecrawl_check_crawl_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Возвращает:

• Ответ включает статус задачи обхода:

6. Инструмент парсинга (firecrawl_parse)

Парсит локальные файлы или ссылки на размещённые загрузки с помощью эндпоинта /v2/parse Firecrawl.

Лучше всего подходит для: PDF, документов Word, электронных таблиц, HTML-файлов и других документов, которым нужен вывод в markdown или структурированном JSON. Размещённый эндпоинт использует двухэтапный процесс загрузки; локальное прямое чтение файлов требует самостоятельно размещённого FIRECRAWL_API_URL.

Не рекомендуется для: удалённых URL (используйте scrape), нескольких файлов в одном вызове (вызывайте parse один раз на файл) или действий только в браузере, таких как скриншоты и клики.

Размещённый эндпоинт: он не может читать вашу файловую систему. Вызовите firecrawl_parse с filePath, чтобы получить короткоживущую команду загрузки и nextToolCall, загрузите файл локально, затем снова вызовите firecrawl_parse с возвращённым uploadRef. Этап загрузки требует авторизации Firecrawl или безключевого уровня. В локальном режиме npx firecrawl-mcp прямое парсинг файлов в настоящее время требует FIRECRAWL_API_URL, указывающего на самостоятельно размещённый API Firecrawl; обычный локальный сервер только с облачным API-ключом не может читать и загружать файлы через этот инструмент.

Пример использования:

{
  "name": "firecrawl_parse",
  "arguments": {
    "filePath": "/absolute/path/to/document.pdf",
    "formats": ["markdown"],
    "parsers": ["pdf"],
    "zeroDataRetention": true
  }
}

Возвращает: Содержимое разобранного документа или инструкции по размещённой загрузке с nextToolCall.

7. Структурированные данные с помощью Scrape JSON

Для структурированных данных с известной страницы вызывайте firecrawl_scrape один раз на URL с formats: ["json"]. Поместите промпт извлечения и JSON-схему в jsonOptions.

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/product",
    "formats": ["json"],
    "jsonOptions": {
      "prompt": "Extract the product name, price, and description.",
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "price": { "type": "number" },
          "description": { "type": "string" }
        },
        "required": ["name", "price"]
      }
    }
  }
}

Когда URL неизвестны или данные охватывают несколько сайтов, используйте firecrawl_agent для многоисточникового исследования.

8. Инструмент агента (firecrawl_agent)

Автономный агент веб-исследований, который возвращает структурированные данные, когда вы не знаете URL или ответ охватывает несколько сайтов. Опишите нужные поля, при необходимости передайте JSON-схему и начальные URL, и агент будет искать, переходить по страницам, читать их и возвращать JSON, собранный из разных источников. Используйте его для сущности с её полями, для списков и наборов данных, а также для страниц, требующих навигации для доступа к данным. Для одного известного URL используйте firecrawl_scrape с форматом JSON.

Как это работает:

Агент выполняет веб-поиск, переходит по ссылкам, читает страницы и собирает данные автономно. Это работает асинхронно — он сразу возвращает ID задачи, а вы опрашиваете firecrawl_agent_status, чтобы проверить завершение и получить результаты.

Асинхронный рабочий процесс:

1. Вызовите firecrawl_agent с вашим промптом/схемой → возвращает ID задачи
2. Занимайтесь другой работой, пока агент исследует (для сложных запросов это может занять минуты)
3. Опрашивайте firecrawl_agent_status с ID задачи для проверки прогресса
4. Когда статус "completed", ответ включает извлечённые данные

Лучше всего подходит для:

• Сложных исследовательских задач, где вы не знаете точных URL
• Сбора данных из нескольких источников
• Поиска информации, разбросанной по сети
• Задач, где можно заниматься другой работой, пока ждёте результатов

Не рекомендуется для:

• Простого скрейпинга одной страницы, когда вы знаете URL (используйте scrape с форматом JSON — быстрее и дешевле)

Аргументы:

• prompt: Описание данных, которые вы хотите, на естественном языке (обязательно, максимум 10 000 символов)
• urls: Необязательный массив URL, чтобы сосредоточить агента на конкретных страницах
• schema: Необязательная JSON-схема для структурированного вывода
• effort: Необязательно. Бюджет рассуждений "low", "medium" или "high" для задачи агента.
• maxCredits: Необязательное положительное целое число. Лимит расходов в кредитах для этого запуска. По умолчанию API использует 2 500, если не указано, и ограничивает бесплатный запрос значением 2 500.
• strictConstrainToURLs: Необязательное логическое значение. Если true, агент посещает только URL из urls.
• threadId: Необязательно. Продолжить существующий поток: threadId из более раннего результата firecrawl_agent или firecrawl_agent_status. Опустите, чтобы начать новый поток. При последующем запросе опущенные настройки mode, urls, schema и exchange переносятся из предыдущего хода.
• mode: Необязательно. "extract" (по умолчанию) возвращает полный структурированный результат на каждом ходе. "chat" позволяет последующему запросу, не требующему новых данных, получить короткий ответ в message вместо повторного запуска; exchange.requireApproval требует этого.
• exchange: Необязательно. Настройки провайдера Alexandria для этого хода, передаваемые как есть в POST /v2/agent:
  • enabled, toolkits (до 5 слагов провайдеров), maxCalls (от 1 до 30), requireApproval (платные вызовы завершают ход с pendingApproval; требует mode: "chat" в том же вызове, даже при последующем запросе)
  • onTermsRequired: что делать, когда провайдер Alexandria, которого агент хотел бы использовать, требует условий обработки данных, которые ваша команда не приняла. Провайдеры с ограничениями никогда не вызываются ни в каком режиме. Если опущено при последующем запросе, сохраняется значение предыдущего хода.
    • "skip" (по умолчанию): отвечать только с принятыми провайдерами. exchange.skippedProviders в результате статуса перечисляет провайдеров с ограничениями, которые могли бы помочь.
    • "ask": то же самое, плюс pendingApproval условий и exchange.requiresAction с ID одобрения и требованиями провайдера. Читайте условия с помощью terms/show; администратор организации принимает их в панели управления Firecrawl.
  • approve: { approvalId, callIds?, always? } отвечает «да» на pendingApproval, которым завершился предыдущий ход. callIds и always применяются только к одобрениям платных вызовов.
  • decline: { approvalId } отвечает «нет». Отклонённое предложение условий исключает этих провайдеров из остальной части потока.
  • approve и decline требуют threadId, и можно отправить только одно из них.

Условия провайдера (режим запроса): режима авто-принятия нет. Когда ход завершается предложением условий, результат статуса содержит pendingApproval (kind: "terms") и exchange.requiresAction с approvalId и требованиями провайдера. Любой дескриптор terms/accept в этой полезной нагрузке API недоступен через MCP. Чтобы использовать провайдера:

1. Покажите пользователю условия (terms/show до firecrawl_scrape с alexandria).
2. Направьте администратора организации принять условия по URL провайдера или в настройках источников данных. Запрос данных не является согласием.
3. Дождитесь, пока администратор подтвердит принятие в панели управления.
4. Продолжите тот же поток: вызовите firecrawl_agent с тем же threadId и exchange.approve: { "approvalId": "..." }. Это возобновляет исследование и не принимает условия.

Если пользователь говорит «нет», вместо этого вызовите firecrawl_agent с тем же threadId и exchange.decline: { "approvalId": "..." }.

Пример запроса:

"Найди основателей Firecrawl и их биографии"

Пример использования (запуск агента, затем опрос результатов):

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "Find the top 5 AI startups founded in 2024 and their funding amounts",
    "schema": {
      "type": "object",
      "properties": {
        "startups": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "funding": { "type": "string" },
              "founded": { "type": "string" }
            }
          }
        }
      }
    }
  }
}

Затем опрашивайте с помощью firecrawl_agent_status, используя возвращённый ID задачи.

Пример использования (с URL — агент сосредоточен на конкретных страницах):

{
  "name": "firecrawl_agent",
  "arguments": {
    "urls": ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
    "prompt": "Compare the features and pricing information from these pages"
  }
}

Пример использования (последующий запрос в том же потоке):

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "Only keep the startups based in Europe",
    "threadId": "0199a1b2-0000-7000-8000-000000000031"
  }
}

Пример использования (продолжение потока после того, как администратор подтвердил принятие в панели управления):

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "The admin confirmed acceptance of the Apollo terms in the dashboard. Continue.",
    "threadId": "0199a1b2-0000-7000-8000-000000000031",
    "exchange": { "approve": { "approvalId": "0199a1b2-0000-7000-8000-000000000033" } }
  }
}

Возвращает:

• ID задачи для проверки статуса, а также threadId и threadTurn. Используйте firecrawl_agent_status для опроса результатов.

9. Проверка статуса агента (firecrawl_agent_status)

Проверяет статус задачи агента и получает результаты по завершении. Используйте это для опроса результатов после запуска агента.

Схема опроса: исследование агента для сложных запросов может занять минуты. Периодически опрашивайте этот эндпоинт (например, каждые 10–30 секунд), пока статус не станет "completed" или "failed".

{
  "name": "firecrawl_agent_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Возможные статусы:

• processing: Агент всё ещё исследует — проверьте позже
• completed: Исследование завершено — ответ включает извлечённые данные
• failed: Произошла ошибка

10. Инструмент взаимодействия (firecrawl_interact)

Взаимодействует со свежим URL или со страницей, которая уже была открыта с помощью firecrawl_scrape.

Лучше всего подходит для: кликов, ввода текста, навигации и извлечения состояния из динамических страниц без восстановления устаревших браузерных инструментов.

Варианты использования:

• Передайте url, чтобы скрейпить и открыть страницу для взаимодействия в одном вызове MCP.
• Передайте scrapeId, чтобы продолжить взаимодействие с уже скрейпленной страницей.
• Чтобы сохранить состояние браузера (cookies, localStorage) в именованный профиль, передайте url с scrapeOptions: { "profile": { "name": "my-profile", "saveChanges": true } }. Состояние сохраняется, когда firecrawl_interact_stop завершает сеанс.
• Передайте ровно одно из url или scrapeId, а также либо prompt, либо code.

Пример использования:

{
  "name": "firecrawl_interact",
  "arguments": {
    "url": "https://example.com",
    "prompt": "Click the pricing link and summarize the visible plans"
  }
}

Возвращает: Результат взаимодействия и, для режима URL, производный scrapeId для последующих действий или очистки.

11. Инструмент остановки взаимодействия (firecrawl_interact_stop)

Останавливает сеанс взаимодействия для скрейпленной страницы, когда вы закончили взаимодействие.

{
  "name": "firecrawl_interact_stop",
  "arguments": {
    "scrapeId": "scrape-id-here"
  }
}

12. Инструменты исследования (firecrawl_research_*)

Поиск и изучение статей и репозиториев GitHub с помощью исследовательских инструментов MCP.

Охватывает: аннотации и полные тексты статей из биомедицинской, естественнонаучной и клинической литературы (PubMed, bioRxiv, medRxiv), а также arXiv и другие научные источники.

Доступные исследовательские инструменты:

• firecrawl_research_search_papers: поиск метаданных и аннотаций статей с помощью запроса на естественном языке, с необязательными фильтрами по автору, категории и дате.
• firecrawl_research_inspect_paper: получение канонических метаданных для одного ID статьи (arXiv, PMC, PMID или DOI).
• firecrawl_research_related_papers: расширение от одной или нескольких опорных статей по графу цитирований.
• firecrawl_research_read_paper: чтение фрагментов полного текста конкретной статьи.

Лучше всего подходит для: обзора литературы, поиска статей и рабочих процессов обнаружения репозиториев, где агенту нужна специализированная исследовательская поверхность вместо общего веб-поиска.

firecrawl_search с categories: ["research"] — это другая поверхность: она фильтрует обычные веб-результаты до сайтов, связанных с исследованиями, и возвращает фрагменты страниц, а не записи статей. Используйте эти инструменты, когда вопрос касается самой литературы, и передавайте несколько различных формулировок одного и того же вопроса, поскольку они выявляют иные статьи, чем один запрос.

13. Инструменты мониторинга (firecrawl_monitor_*)

Создание и управление повторяющимися мониторами страниц. Мониторы выполняют запланированные скрейпинги или обходы, сравнивают каждый результат с последним сохранённым снимком и могут уведомлять через webhook или электронную почту.

Лучше всего подходит для:

• Наблюдения за одной страницей или несколькими страницами с течением времени
• Оповещения о значимых изменениях с использованием цели на простом языке
• Отслеживания истории проверок и различий на уровне страниц

Рекомендуемый шаблон создания:

Используйте page или pages вместе с goal. Сервер MCP формирует запрос монитора с расписанием в 30 минут, а API автоматически включает оценку значимых изменений.

Оценка значимых изменений выполняется автоматически, когда задан goal. Webhook страниц предоставляют isMeaningful и judgment для событий monitor.page.

Пишите цели как краткие инструкции для монитора из 2-3 предложений. Укажите, что должно вызывать оповещение, сохраните любые рамки, заданные пользователем, и включайте исключения, специфичные для намерения, только когда они очевидны из запроса. Общий шум, такой как пробелы, изменения только форматирования, идентификаторы запросов, параметры отслеживания, общие метаданные и не связанные с содержимым элементы страницы, уже обрабатывается оценщиком, поэтому не повторяйте это в каждой цели. Если пользователь неконкретен, оставьте цель широкой; если он просит широкий мониторинг или «любое изменение», сохраните это. Если пользователь говорит, что что-то его не интересует, укажите это явно.

{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "page": "https://example.com/pricing",
    "goal": "Alert when pricing, packaging, or launch messaging changes."
  }
}

Несколько страниц с webhook:

{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "pages": ["https://example.com/pricing", "https://example.com/changelog"],
    "goal": "Alert when pricing, packaging, or launch messaging changes.",
    "webhookUrl": "https://example.com/webhooks/firecrawl"
  }
}

Расширенные запросы на создание:

Передайте body, когда вам нужны цели обхода, отслеживание изменений в JSON, пользовательское хранение или явное управление judgeEnabled.

{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "body": {
      "name": "Docs monitor",
      "schedule": { "text": "hourly", "timezone": "UTC" },
      "goal": "Alert when docs pages add, remove, or materially change API behavior.",
      "targets": [{ "type": "crawl", "url": "https://example.com/docs" }]
    }
  }
}

Другие инструменты мониторинга:

• firecrawl_monitor_list: список мониторов.
• firecrawl_monitor_get: получить один монитор.
• firecrawl_monitor_update: обновить поля, включая goal, judgeEnabled, webhook и notification.
• firecrawl_monitor_run: запустить проверку немедленно.
• firecrawl_monitor_delete: удалить монитор (деструктивно; вызывайте только когда пользователь намерен его удалить).
• firecrawl_monitor_checks: список проверок, при необходимости отфильтрованный по статусу.
• firecrawl_monitor_check: получить результаты на уровне страниц, включая diff, snapshot, judgment.meaningful и judgment.meaningfulChanges.

14. Инструмент поиска для разработчиков (firecrawl_developer_search)

Поиск по индексу, созданному для агентов-программистов. Индекс охватывает issues GitHub, объединённые pull request'ы, README репозиториев и документацию по коду.

Лучше всего подходит для: вопроса по программированию: поведение кода, библиотека или фреймворк, контракт API, сообщение об ошибке или известная ошибка.

Аргументы:

{
  "name": "firecrawl_developer_search",
  "arguments": {
    "query": "how do I configure retries",
    "k": 10,
    "skills": "only"
  }
}

• query (обязательно): вопрос разработчика или поисковая фраза.
• k: количество ранжированных результатов. По умолчанию 10, максимум 100.
• skills: установите в "only", чтобы искать только в файлах агентских навыков.

Возвращает: ранжированные результаты. Каждый результат содержит ID, тип источника (issue, pull_request, readme или doc), URL, заголовок и совпавшие фрагменты в markdown.

firecrawl_search с categories: ["developer"] выполняет поиск по тому же индексу рядом с веб-результатами. Используйте этот инструмент вместо него, когда вам нужны совпавшие фрагменты, фильтр skills или отсутствие веб-результатов в ответе. Конечная точка только для поиска предоставляет оба инструмента, и тот же выбор применим и там.

14b. Инструмент поиска по правительственному индексу (firecrawl_gov_search)

Поиск первичных правовых и нормативных материалов из федеральных, региональных и местных правительственных источников США: статуты, нормативные акты, кодексы, судебные решения и другие правительственные публикации.

Лучше всего подходит для: правового или нормативного вопроса, требующего действующего текста или официального правительственного источника.

Аргументы:

{
  "name": "firecrawl_gov_search",
  "arguments": {
    "query": "excessive force claims against police officers",
    "k": 10,
    "courtType": "federal-appellate",
    "cites": "42 U.S.C. § 1983"
  }
}

• query (обязательно): правовой или нормативный вопрос или поисковая фраза.
• k: количество ранжированных результатов. По умолчанию 10, максимум 100.
• jurisdiction: оставить только страницы одной юрисдикции: "us" для федеральной или "us-" плюс двухбуквенный код штата или территории, например "us-ca" или "us-dc".
• court: оставить только страницы, помеченные для одного суда, по идентификатору суда CourtListener, например "scotus", "ca9" или "nysd".
• courtType: оставить только страницы одного типа суда: federal-supreme, federal-appellate, federal-district, federal-bankruptcy, federal-special, military, state-supreme, state-appellate, state-trial, state-special или state-attorney-general.
• cites: оставить только страницы, ссылающиеся на один закон или дело, в виде печатной ссылки, например "42 U.S.C. § 1983" или "5 U.S. 137", или идентификатора ссылки, например "us:usc:42:1983".
• domain: оставить только страницы одного сайта, например "irs.gov".

Фильтры необязательны и комбинируются: результат должен соответствовать каждому заданному фильтру. Фильтры оставляют только страницы, помеченные индексом, поэтому отфильтрованный поиск может исключить релевантные страницы, и отсутствие результатов не означает, что их нет. Метки судов наиболее полны для федеральных судов и коллекций судебной практики.

Возвращает: ранжированные результаты. Каждый результат содержит позицию, заголовок, URL и совпавший фрагмент. Конечная точка только для поиска также предоставляет этот инструмент.

firecrawl_search с categories: ["gov"] выполняет поиск по тем же источникам и возвращает совпадения в data.web с category: "gov". Категория gov не принимает эти фильтры и не может комбинироваться с другими категориями.

15. Инструменты Alexandria

Firecrawl Alexandria — это каталог поставщиков данных, доступных через API Firecrawl с ключом API Firecrawl в команде с доступом к Alexandria. Сессии без ключа (размещённые или локальные) получают Alexandria requires an API key on a team with Alexandria access; инструменты обнаружения Alexandria не перечисляются для размещённых сессий без ключа.

Семантическое обнаружение (firecrawl_search):

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "podcast conversations about AI agents",
    "sources": ["web", "alexandria"],
    "domainTools": true,
    "limit": 2
  }
}

data.tools по умолчанию возвращает компактные предложения с поставщиком, возможностью и описанием. Установите toolDetail: "summary" для метаданных и навигации или toolDetail: "full" для контрактов, включая входные данные, поля ответа и примеры. domainTools: true добавляет контекстные совпадения к упоминаниям в запросе и URL результатов в том же массиве. Проверьте warning на предмет недоступного обнаружения. Поиск требует запроса и не принимает фильтры обхода каталога. Это обнаружение работает как на полной, так и на поисковой поверхности MCP.

Постепенное раскрытие (firecrawl_find_tools):

{
  "name": "firecrawl_find_tools",
  "arguments": {
    "providers": ["particle"],
    "capabilities": ["podcasts/episodes/search"],
    "expand": ["options", "response", "examples"],
    "limit": 2
  }
}

Начните без аргументов, чтобы получить категории, затем постепенно сужайте каталог:

Аргументы	Результат
{}	Категории и краткие описания
{"categories":["podcasts"]}	Поставщики в этой категории
{"categories":["podcasts"],"providers":["particle"]}	Компактные имена и описания инструментов
{"providers":["particle"],"capabilities":["podcasts/episodes/search"]}	Полные выбранные входные данные, ограничения, ответ и примеры

Переход по группам не требуется. Явный level поддерживает categories, providers, groups или tools; явный expand выбирает разделы контракта. expand: [] сохраняет результаты компактными даже при выборе возможности. Для широких полных контрактов явно запросите level: "tools" и expand: ["options", "response", "examples"]. URL обеспечивают контекстное обнаружение без загрузки страницы. Результаты инструментов опускают цены в кредитах для каждой возможности, если не задан includeCosts: true; последующие аргументы nextTool сохраняют его.

Результаты находятся в data.alexandria[0].data. Переходите по nextTool элемента, вызывая его name с его arguments; nextTool страницы продвигает пагинацию. Существующие объекты next остаются вызовами обнаружения Alexandria, используемыми через firecrawl_scrape. Обнаружение стоит ноль кредитов и никогда не выполняет инструменты поставщика. Прочитайте выбранный полный контракт перед выполнением.

Эти элементы управления требуют соответствующего развёртывания API Alexandria.

Выполнение (firecrawl_scrape с alexandria): передайте alexandria вместо url (ровно одно из двух; также могут быть указаны requestId и timeout). Принимается один вызов или массив до десяти вызовов.

{
  "name": "firecrawl_scrape",
  "arguments": {
    "alexandria": [
      {
        "provider": "fred",
        "capability": "series/observations",
        "options": { "series_id": "CPIAUCSL" }
      }
    ]
  }
}

Возвращает: { success, scrape_id, requestId, data: { alexandria: [...], creditsCost } }. Каждый элемент — либо результат (provider, capability, data, records, upstreamStatus), либо error с code; пакет никогда не завершается неудачей целиком из-за ошибки поставщика, а data.creditsCost — это общая сумма, списанная за запрос. Тела ошибок Alexandria (403 без доступа к Alexandria и статусы биллинга 402/409) передаются в полосе с их code.

Выполнение генерирует один x-request-id и возвращает его при успехе или неудаче. Повторите идентичную полезную нагрузку с этим requestId; не создавайте новый ID после неопределённого исхода. Доступные кредиты проверяются API.

Поставщик Alexandria, условия которого команда не приняла, завершается с ошибкой до запуска чего-либо с HTTP 403 и этим телом:

{
  "success": false,
  "code": "THIRD_PARTY_DATA_TERMS_REQUIRED",
  "error": "An organization admin must accept the benzinga provider's terms (version 2026-09-12-placeholder) before this request can run. Accept them at https://www.firecrawl.dev/app/alexandria/benzinga",
  "requiresAction": {
    "type": "accept_terms",
    "terms": "benzinga",
    "version": "2026-09-12-placeholder",
    "url": "https://www.firecrawl.dev/app/alexandria/benzinga"
  }
}

Результат инструмента передаёт это как ошибку, где structuredContent содержит code, status: 403, requestId, объект requiresAction без изменений и next_actions (human_action_required, затем retry_same_request). Принятие условий — юридический акт, поэтому администратор организации принимает их в панели управления Firecrawl, а не через MCP. Используйте возвращённый вызов nextTool, чтобы прочитать соглашение через firecrawl_scrape с alexandria: [{provider: "firecrawl", capability: "terms/show", options: {provider: "<provider>"}}], отправленным отдельно от выполнения поставщика, и представьте его пользователю. Затем администратор организации принимает его по адресу requiresAction.url или по адресу https://www.firecrawl.dev/app/settings?tab=data-sources. firecrawl_scrape отклоняет любую другую возможность terms/*, поэтому не вносит изменений в аккаунт. Запрос данных не является согласием, и никакого автоматического принятия или неопределённых повторов не происходит. За заблокированное извлечение кредиты не списываются. После того как администратор подтвердит принятие, вызовите тот же инструмент снова с идентичной полезной нагрузкой и requestId.

16. Инструмент использования кредитов

Инструмент требует аутентифицированного аккаунта Firecrawl и работает только на чтение.

• firecrawl_credit_usage по умолчанию равен { "view": "current" } и возвращает remainingCredits, planCredits, billingPeriodStart и billingPeriodEnd. Оставшиеся кредиты могут превышать кредиты плана, если у команды есть пополнения или гранты.
• Передайте { "view": "historical" } для периодов календарного месяца, содержащих startDate, endDate и creditsUsed. Передача { "byApiKey": true } также выбирает историческое представление и разбивает периоды по API-ключу; тогда каждая строка включает apiKey. Передача { "byEndpoint": true } вместо этого разбивает периоды по эндпоинту, который использовал кредиты (scrape, search, crawl, map, agent, ...); тогда каждая строка включает endpoint. Передайте { "bin": "day" } для одного периода на каждый день UTC вместо каждого календарного месяца. Не комбинируйте byApiKey с byEndpoint или любой из них с { "view": "current" }. Значение endDate последнего периода может быть null. Если Firecrawl API ещё не предлагает разбивку по эндпоинтам или дневные периоды, результат содержит notice и месячные показатели.

Программное использование (нестабильно)

Пакет также предоставляет точку входа библиотеки для встраивания сервера в другую среду выполнения. Она нестабильна: API, его параметры и его типы могут меняться в любом релизе, включая минорные и патч-релизы, поэтому закрепляйте точную версию.

npm install --save-exact firecrawl-mcp zod

В примере параметры инструментов определяются с помощью zod, поэтому встраивающий проект устанавливает его как собственную зависимость.

import { createFirecrawlMcpServer } from 'firecrawl-mcp/server';
import { z } from 'zod';

const server = createFirecrawlMcpServer({
  transport: 'httpStream',
  apiKey: process.env.FIRECRAWL_API_KEY,
  unstable_hooks: {
    registerExtraTools: (registrar) => {
      registrar.addTool({
        name: 'my_tool',
        description: 'An extra tool served next to the Firecrawl tools.',
        parameters: z.object({ text: z.string() }),
        execute: async ({ text }) => text,
      });
    },
  },
});

await server.start({
  transportType: 'httpStream',
  httpStream: { port: 3000, host: '127.0.0.1', endpoint: '/mcp', stateless: true },
});
// MCP endpoint: http://127.0.0.1:3000/mcp

Задайте host явно. Без него сервер слушает на localhost, который Node привязывает к одному адресу (часто только к ::1), поэтому запросы к 127.0.0.1 отклоняются. Используйте 0.0.0.0 или ::, чтобы принимать подключения с других машин только за сетевыми контролями доступа или проверкой unstable_hooks.authenticate: без неё каждому вызывающему, который может достичь порта, предоставляется доступ с настроенным apiKey.

Библиотека не проверяет Host или Origin, если её об этом не попросят, а её заголовки CORS разрешают любой источник. Сервер, доступный из браузера на той же машине, должен передавать httpStream.allowedHosts (например, ['localhost', '127.0.0.1', '[::1]']): запросы, чей заголовок Host или Origin указывает другой хост, тогда получают 403 (кроме GET и HEAD на пути проверки работоспособности), а заголовки CORS отражают разрешённый источник. Командная строка задаёт этот список в локальном режиме HTTP.

Параметры повторяют переменные окружения CLI: apiUrl, apiKey, transport, logging, safeMode, fileAccess (local или upload), requireCredential, searchFeedback и endpointFeedback. unstable_hooks принимает:

Хук	Назначение
authenticate(request)	Определяет сессию для запроса; выбросьте Response, чтобы отклонить его.
wrapTool(tool)	Декорирует каждый зарегистрированный инструмент.
onToolResult(event)	Наблюдает за началом и результатом каждого вызова инструмента.
instructions	Инструкции сервера или функция, выбирающая из значений по умолчанию.
registerExtraTools(registrar, context)	Добавляет инструменты после встроенных.
outboundRequest(session)	Учётные данные и дополнительные заголовки для каждого запроса к Firecrawl API.
beforeKeylessRequest(session, origin)	Отклоняет запрос без ключа, выбрасывая исключение.
toolFilter(name)	Исключает встроенные инструменты из экземпляра.
configureHttp(app)	Добавляет HTTP-маршруты.
oauth.protectedResource	Обслуживает метаданные защищённого ресурса OAuth.

Сервер построен на официальном MCP TypeScript SDK (@modelcontextprotocol/server). Используйте типы, экспортируемые из firecrawl-mcp/server (Session, ToolDefinition, ToolRegistrar, FirecrawlMcpServerHooks и другие), а не собственные типы SDK.

Точка входа также экспортирует вспомогательные функции, которые используют встроенные инструменты, такие как recoveryPayload, normalizeHeader, requestOrigin, isRuntimeUserAgent, initializeClientSlug, searchToolBaseFields, searchOutputSchema и structuredCompact, чтобы дополнительные инструменты и хуки могли соответствовать встроенному поведению. Они также нестабильны.

Система логирования

Сервер включает комплексное логирование:

• Статус и прогресс операций
• Метрики производительности
• Отслеживание ограничений скорости
• Условия ошибок

Примеры сообщений лога:

[INFO] Firecrawl MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[ERROR] Rate limit exceeded

Обработка ошибок

Сервер обеспечивает надёжную обработку ошибок:

• Ошибки ограничения скорости API, передаваемые MCP-клиенту
• Подробные сообщения об ошибках
• Устойчивость к сетевым сбоям

Пример ответа с ошибкой:

{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded"
    }
  ],
  "isError": true
}

Разработка

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

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

1. Сделайте форк репозитория
2. Создайте ветку для своей функции
3. Запустите тесты: npm test
4. Отправьте pull request

Благодарности участникам

Спасибо @vrknetha, @cawstudios за первоначальную реализацию!

Спасибо MCP.so и Klavis AI за хостинг и @gstarwd, @xiangkaiz и @zihaolin96 за интеграцию нашего сервера.

Лицензия

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

Структурированные данные и большие результаты

Аутентифицированный поиск по умолчанию использует веб-результаты, семантические инструменты Alexandria и совпадения по доменам. Начинайте с фактического вопроса. Используйте firecrawl_find_tools для прямого семантического поиска инструментов, выбранных контрактов или прогрессивного просмотра: категории → провайдеры → компактные инструменты → выбранный контракт. Выполняйте инструменты через firecrawl_scrape; обычное сканирование URL и поиск никогда не выполняют инструменты провайдера автоматически.

Для выбранных контрактов предпочитайте expand: ["options", "response"] и запрашивайте примеры только если форма входных данных неясна. Изучайте связанные возможности вместе и повторно используйте возвращённые контракты.

Для потенциально большого результата рабочего процесса укажите и сохраните requestId верхнего уровня перед выполнением. Этот ID остаётся доступным, даже если клиент отклонит ответ. Обычные сканирования URL вместо этого используют возвращённый ID сканирования.

Для большого сохранённого результата рабочего процесса или обычного сканирования вызовите firecrawl_scrape с:

{
  "alexandria": {
    "provider": "firecrawl",
    "capability": "bash",
    "options": {
      "requestId": "<source-request-or-scrape-id>",
      "command": "ls -lh"
    }
  }
}

Прочитайте stdout, stderr, exitCode и workspaceId в data.alexandria[0].data. Продолжите с options: {workspaceId, command}, чтобы изучить response.json с помощью jq, или document.md с помощью ограниченных текстовых команд для обычных сканирований. Держите вывод избирательным. Загрузка источника должна быть отдельным вызовом; её вложенный ID источника отличается от ID запроса выполнения верхнего уровня. Рабочие пространства истекают после пяти минут простоя, и не каждый результат сохраняется (включая ZDR и полезные нагрузки рабочих процессов API-провайдера). ID поиска не поддерживаются.

Для источников рабочих процессов response.json сохраняет конверт API: выберите .data.alexandria[].data, затем response.key выбранного контракта, если он непустой. Объединяйте связанные подсчёты и проекции в одной команде Bash, когда эта форма известна, вместо повторного изучения ключей.

Успешные ответы выполнения Alexandria объёмом более 20 000 оценочных токенов (сериализованные байты UTF-8, делённые на четыре) возвращают небольшую передачу после того, как удалённый Bash подтвердит доступность полной партии. Следуйте nextTool, чтобы изучить сохранённые данные. Это добавляет один вызов Bash и запускает рабочее пространство с пятиминутным TTL простоя. Полная полезная нагрузка сохраняется. Если подтверждение не удаётся, исходный ответ остаётся встроенным. Поиск, обычное сканирование URL, ответы с ошибками и служебные вызовы Firecrawl не изменяются. Этот бюджет доставки не измеряет оставшийся контекст клиента; локальный кэш результатов процесса не добавляется. Когда доступны локальные инструменты файловой системы, сохранение вывода CLI и чтение выбранных разделов — ещё один вариант.

Последовательность обнаружения CLI соответствует этим вызовам MCP:

Намерение	Инструмент	Аргументы
Веб + семантические + доменные инструменты	firecrawl_search	{"query":"<user question>"}
Только семантические инструменты	firecrawl_search	{"query":"<user question>","sources":["alexandria"]}
Категории	firecrawl_find_tools	{}
Провайдеры в категории	firecrawl_find_tools	{"categories":["<category-id>"]}
Компактные инструменты провайдера	firecrawl_find_tools	{"providers":["<provider-id>"]}
Выбранный контракт	firecrawl_find_tools	{"providers":["<provider-id>"],"capabilities":["<capability-id>"]}
Выполнение	firecrawl_scrape	{"alexandria":{"provider":"<provider-id>","capability":"<capability-id>","options":{"<required-field>":"<value>"}}}

Find Tools и выполнение доступны как на полной поверхности, так и на поверхности поиска. Повторно используйте полный контракт из поиска, если он присутствует, вместо выполнения ещё одного вызова обнаружения. Следуйте возвращённой навигации nextTool только когда нужно больше результатов.

Обратная связь по сессии Alexandria

Существующий инструмент firecrawl_feedback принимает endpoint: "alexandria":

{
  "endpoint": "alexandria",
  "rating": "partial",
  "requestedWebsite": {
    "url": "https://example.com",
    "requestedFunctionality": "Find records and download their attachments"
  },
  "objective": "Compare contract requirements across agencies before bidding",
  "rationale": "Found summaries but could not retrieve attachments"
}

Необязательный objective — это основная цель сессии: чего в конечном итоге пытался достичь агент или его пользователь, помимо отдельного сайта в requestedWebsite.

Это использует аутентифицированный POST /v2/feedback, без ID задания. Оно должно поступить в течение 20 минут после последнего поиска, обнаружения или выполнения Alexandria команды; более поздняя обратная связь отклоняется с FEEDBACK_WINDOW_EXPIRED. Подходящая обратная связь может вернуть 1 кредит с учётом дневных лимитов в 10 кредитов на сайт и 100 кредитов на команду (день UTC). После любого из лимитов обратная связь всё равно записывается без возврата, а ответ устанавливает websiteCapReached или dailyCapReached. Необязательные массивы providerFeedback и capabilityFeedback описывают пробелы в покрытии и проблемы выполнения; схема инструмента перечисляет поддерживаемые значения проблем. new_capability_request требует requestedFunctionality; missing_capability (провайдер существует, но не имеет возможности) — нет. Применяются существующие отказы от обратной связи и средства контроля аутентификации.

Подходящие результаты выполнения и обнаружения Alexandria включают указатель feedbackTool с именем инструмента и скелетом аргументов. Указатель опускается для внутренних вызовов Firecrawl, таких как bash, и когда firecrawl_feedback не зарегистрирован (FIRECRAWL_NO_ENDPOINT_FEEDBACK или запуск без ключа).