Firecrawl MCP Server

Model Context Protocol (MCP) сервер, который приносит Firecrawl в MCP-совместимых AI-агентов — поиск, сбор данных и взаимодействие с живым вебом для чистого, готового к использованию контекста.

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

Особенности

Поиск в вебе и получение полного содержания страницы
Извлечение содержимого любого URL в чистые, структурированные данные
Взаимодействие со страницами — клики, навигация и управление
Глубокое исследование с автономным агентом
Автоматические повторные попытки и ограничение скорости
Поддержка облака и локального развёртывания
Поддержка SSE

Поэкспериментируйте с нашим MCP Server в playground на MCP.so или на Klavis AI.

Установка

Hosted MCP (беспроорный бесплатный тариф)

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

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

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

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

https://mcp.firecrawl.dev/{FIRECRAWL_API_KEY}/v2/mcp

См. документацию по MCP серверам и руководство по onboarding агента для деталей настройки.

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

Открыта также обезличенная поверхность только для чтения и поиска:

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

Она предоставляет фиксированный набор из шести инструментов только для чтения: firecrawl_search и пять инструментов firecrawl_research_*. Она не выполняет извлечение содержания страниц и имеет собственную OAuth-идентификацию; полный эндпоинт выше остаётся без изменений. См. docs/search-profile.md для полного контракта.

Запуск через 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-серверов:

Cursor MCP Server Configuration Guide

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

Откройте Настройки Cursor
Перейдите в Features > MCP Servers
Нажмите «+ Add new global MCP server»
Вставьте следующий код:

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

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

Откройте Настройки Cursor
Перейдите в Features > MCP Servers
Нажмите «+ Add New MCP Server»
Введите следующее:

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 на ваш Firecrawl API key. Если у вас его ещё нет, создайте аккаунт и получите ключ на 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 Local Mode

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

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

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

Установка через Smithery (Legacy)

Чтобы автоматически установить Firecrawl для Claude Desktop через Smithery:

npx -y @smithery/cli install @mendableai/mcp-server-firecrawl --client claude

Работа в 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}"
      }
    }
  }
}

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

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

Требуется для облачного API

FIRECRAWL_API_KEY: Ваш Firecrawl API key

Требуется при использовании облачного API (по умолчанию)

Optional when using self-hosted instance with FIRECRAWL_API_URL
FIRECRAWL_API_URL (Optional): Пользовательный API-эндпойнт для self-hosted экземпляров

Пример: https://firecrawl.your-domain.com

Если не указан, будет использоваться облачный API (требуется API key)

MCP OAuth (Bearer access tokens)

Hosted Firecrawl может выдавать OAuth access tokens (fco_…) через сервер авторизации на firecrawl.dev. Этот MCP сервер переадресует любые учётные данные, которые он разрешает, в Firecrawl API как Authorization: Bearer ….

HTTP stream transports (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 для статического access token, либо продолжайте использовать FIRECRAWL_API_KEY для API key.

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

Поверхность поиска только (hosted)

В режиме hosted запускается второй инстанс внутри процесса, обслуживающий endpoint для поиска только. Встроенный сервис имеет фиксированный контракт развёртывания: nginx проксирует /v2/mcp-search во внутренний инстанс на локальный порт 3001, а идентификатор защищённого ресурса OAuth — https://mcp.firecrawl.dev/v2/mcp-search.

FIRECRAWL_MCP_SEARCH_ENABLED (по умолчанию true) — поддерживаемый режим работы; установите в false, чтобы не запускался инстанс поиска. Узел Node также принимает FIRECRAWL_MCP_SEARCH_PORT, FIRECRAWL_MCP_SEARCH_ENDPOINT и FIRECRAWL_MCP_SEARCH_RESOURCE_URL для изоляционных тестов. Эти переопределения не перенастраивают маршруты nginx и не изменяют allowlist сервера авторизации и не должны использоваться независимо в hosted-развертывании.

Поиск требует аутентификацию для каждого запроса (включая tools/list) и отклоняет OAuth-токены, чей аудиторию не совпадает с его собственным ресурсом.

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

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

export FIRECRAWL_API_KEY=your-api-key

Для self-hosted экземпляра:

# Обязательно для self-hosted
export FIRECRAWL_API_URL=https://firecrawl.your-domain.com

# Необязательно аутентификация для self-hosted
export FIRECRAWL_API_KEY=your-api-key  # Если ваш инстанс требует аутентификацию

Использование с 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-операций, используйте пакетный endpoint Firecrawl API вне MCP.
Если нужно обнаружить URL на сайте: используйте map
Если нужно найти информацию в вебе: используйте search
Если нужна сложная исследовательская работа по нескольким неизвестным источникам: используйте agent
Если нужно проанализировать весь сайт или раздел: используйте crawl (с учётом лимитов!)
Если нужна интерактивная автоматизация браузера (клик, набор текста, навигация): используйте interact с URL для новой страницы, или сочетайте scrape + interact, когда страница уже скраплена или нужен более точный контроль скрапинга

Быстрая справка по инструментам

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

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

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

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

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

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

Извлекает контент с одной URL с продвинутыми опциями.

Наилучшее применение:

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

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

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

Типичные ошибки:

Передача списка URL в один вызов scrape. Вызывайте scrape по одному URL за каждый вызов в MCP. Если нужен пакетный 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, чтобы вернуть контент с вырезанной персональной информацией.

Возвращает:

JSON-структурированные данные, Markdown, branding-профиль или другие форматы по запросу.

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

Картирует сайт и обнаруживает все проиндексированные URL.

Лучшее использование:

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

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

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

Типичные ошибки:

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

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

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

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

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

Возврат:

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

3. Инструмент Поиска (`firecrawl_search`)

Поиск в вебе и, при желании, извлечение контента из результатов поиска.

Лучшее применение:

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

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

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

Типичные ошибки:

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

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

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "latest AI research papers 2023",
    "highlights": true,
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true,
      "redactPII": true
    }
  }
}

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

Возвращает:

Массив результатов поиска (с опциональным Scrape-содержанием), плюс поле id. Передайте этот id в firecrawl_search_feedback после того, как вы использовали результаты, чтобы вернуть 1 кредит (поиск стоит 2).

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

"Найди последние научные работы по AI, опубликованные в 2023 году."

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

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

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

Отказ от использования: установите FIRECRAWL_NO_SEARCH_FEEDBACK=1 (или FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1) в окружении при запуске MCP сервера. Инструмент firecrawl_search_feedback не будет зарегистрирован, поэтому агенты не смогут его вызывать. Руководители команды могут также отключить сбор отзывов на стороне сервера; в таком случае инструмент зарегистрирован, но всегда возвращает feedbackErrorCode: "TEAM_OPTED_OUT".

Самое важное поле: missingContent. Это массив конкретных элементов контента, которых агент ожидал найти, но не нашёл. По одному элементу на тему — такие данные суммируются между командами и подсказывают, что индексировать дальше.

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

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

{
  "name": "firecrawl_search_feedback",
  "arguments": {
    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "good",
    "valuableSources": [
      {
        "url": "https://docs.firecrawl.dev/features/search",
        "reason": "Most up-to-date description of /search."
      }
    ],
    "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'"
  }
}

Возвращает:

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

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

Отправляет структурированную обратную связь по завершённой задаче в v2 endpoint через /v2/feedback.

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

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

Отказ от использования: установите 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"
    }
  }
}

Возвращает:

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

4. Инструмент Crawl (`firecrawl_crawl`)

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

Лучшее применение:

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

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

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

Предупреждение: ответы crawl могут быть очень большими и превзойти ограничение по токенам. Ограничьте глубину crawl и число страниц, или используйте 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
  }
}

Возврат:

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

5. Проверка статуса Crawl (`firecrawl_check_crawl_status`)

Проверка статуса и результатов существующей задачи crawl по ID.

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

Возврат:

Ответ включает статус задачи crawl:

6. Инструмент Parse (`firecrawl_parse`)

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

Лучшее применение: PDF, Word документы, таблицы, HTML-файлы и другие документы, требующие Markdown или структурированного JSON-вывода. Hosted MCP поддерживает двустадийный поток загрузки через upload-ref; чтение локальных файлов требует self-hosted FIRECRAWL_API_URL.

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

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

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

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

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

7. Инструмент Extract (`firecrawl_extract`)

Извлекает структурированную информацию с веб-страниц с использованием возможностей LLM. Поддерживает как облачные AI, так и self-hosted извлечение.

Лучшее применение:

Извлечение конкретных структурированных данных, таких как цены, названия, детали

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

Когда нужен полный контент страницы (используйте scrape)
Когда не нужен структурированный набор данных

Аргументы:

urls: массив URL-ов для извлечения информации
prompt: пользовательский запрос для LLM-извлечения
systemPrompt: системный промпт подталкивающий LLM
schema: JSON-схема для структурированного извлечения
allowExternalLinks: разрешить извлечение из внешних ссылок
enableWebSearch: включить веб-поиск для дополнительного контекста
includeSubdomains: включать поддомены в извлечение

При использовании self-hosted инстанса извлечение будет происходить с вашим настроенным LLM. Для облачного API используется управляемый сервис Firecrawl.

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

{
  "name": "firecrawl_extract",
  "arguments": {
    "urls": ["https://example.com/page1", "https://example.com/page2"],
    "prompt": "Extract product information including name, price, and description",
    "systemPrompt": "You are a helpful assistant that extracts product information",
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "price": { "type": "number" },
        "description": { "type": "string" }
      },
      "required": ["name", "price"]
    },
    "allowExternalLinks": false,
    "enableWebSearch": false,
    "includeSubdomains": false
  }
}

Возвращает:

Извлечённые структурированные данные в соответствии с вашей схемой

{
  "content": [
    {
      "type": "text",
      "text": {
        "name": "Example Product",
        "price": 99.99,
        "description": "This is an example product description"
      }
    }
  ],
  "isError": false
}

8. Инструмент Agent (`firecrawl_agent`)

Автономный агент веб-исследований. Это отдельный слой AI-агента, который независимо просматривает интернет, ищет информацию, переходит по ссылкам, читает страницы и извлекает структурированные данные по вашему запросу.

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

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

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

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

Лучшее применение:

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

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

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

Аргументы:

prompt: Естественно-языковое описание необходимой информации (обязательно, максимум 10 000 знаков)
urls: По желанию массив URL-ов, чтобы сфокусировать агента на конкретных страницах
schema: По желанию JSON-схема для структурированного вывода

Пример промпта:

"Find the founders of Firecrawl and their backgrounds"

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

{
  "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"
  }
}

Возврат:

ID задачи для отслеживания статуса. Используйте 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. Инструмент Interact (`firecrawl_interact`)

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

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

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

Передать url, чтобы открыть страницу и начать взаимодействовать в одном MCP-вызове.
Передать scrapeId, чтобы продолжить взаимодействие с существующей скрап-страницей.
Передать ровно одно из 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. Остановка Interact (`firecrawl_interact_stop`)

Остановить сессию взаимодействия с скрапенной страницей после завершения.

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

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

Поиск и обзор статей и GitHub репозиториев через исследовательские MCP-инструменты.

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

firecrawl_research_search_papers: поиск научных статей
firecrawl_research_inspect_paper: обзор одной статьи
firecrawl_research_related_papers: поиск связанных статей
firecrawl_research_read_paper: чтение содержания статьи
firecrawl_research_search_github: поиск репозиториев на GitHub

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

13. Мониторинговые инструменты (`firecrawl_monitor_*`)

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

Лучшее применение:

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

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

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

Оценка значимых изменений выполняется автоматически, когда установлен goal. Вебхуки страниц expose 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."
  }
}

Несколько страниц с вебхуками:

{
  "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, если нужно целевые URL-ы для скана, отслеживание изменений в 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.

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

Сервер включает обширное логирование:

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

Примеры логов:

[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
}

Разработка

# Установка зависимостей
npm install

# Сборка
npm run build

# Запуск тестов
npm test

Вклад

Форкните репозиторий
Создайте ветку для вашей фичи
Запустите тесты: npm test
Оправьте pull request

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

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

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

Лицензия

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

Firecrawl MCP Server

Особенности

Установка

Hosted MCP (беспроорный бесплатный тариф)

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

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

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

Работа в Cursor

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

Запуск в Streamable HTTP Local Mode

Установка через Smithery (Legacy)

Работа в VS Code

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

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

Требуется для облачного API

MCP OAuth (Bearer access tokens)

Поверхность поиска только (hosted)

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

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

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

Быстрая справка по инструментам

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

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

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

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

3. Инструмент Поиска (firecrawl_search)

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

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

4. Инструмент Crawl (firecrawl_crawl)

5. Проверка статуса Crawl (firecrawl_check_crawl_status)

6. Инструмент Parse (firecrawl_parse)

7. Инструмент Extract (firecrawl_extract)

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

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

10. Инструмент Interact (firecrawl_interact)

11. Остановка Interact (firecrawl_interact_stop)

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

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

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

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

Разработка

Вклад

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

Лицензия

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

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

3. Инструмент Поиска (`firecrawl_search`)

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

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

4. Инструмент Crawl (`firecrawl_crawl`)

5. Проверка статуса Crawl (`firecrawl_check_crawl_status`)

6. Инструмент Parse (`firecrawl_parse`)

7. Инструмент Extract (`firecrawl_extract`)

8. Инструмент Agent (`firecrawl_agent`)

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

10. Инструмент Interact (`firecrawl_interact`)

11. Остановка Interact (`firecrawl_interact_stop`)

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

13. Мониторинговые инструменты (`firecrawl_monitor_*`)