Firecrawl MCP Server

официальный

Добавляет мощные возможности веб-скрапинга и поиска для LLM-клиентов, таких как Cursor и Claude.

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

Firecrawl MCP Server

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

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

Возможности

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

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

Установка

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

Чтобы настроить 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 на ваш 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"
      }
    }
  }
}

Запуск в локальном режиме с потоковой передачей HTTP

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

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

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

Установка через Smithery (устаревший способ)

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

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

Запуск в VS Code

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

Для ручной установки добавьте следующий блок JSON в файл пользовательских настроек (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: Ваш API-ключ Firecrawl
- Обязателен при использовании облачного API (по умолчанию)
- Необязателен при использовании собственного экземпляра с FIRECRAWL_API_URL
FIRECRAWL_API_URL (Необязательно): Пользовательская конечная точка API для собственных экземпляров
- Пример: https://firecrawl.your-domain.com
- Если не указано, будет использоваться облачный API (требуется API-ключ)

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 извлечения/поиска.

Дополнительная конфигурация

Конфигурация повторных попыток

FIRECRAWL_RETRY_MAX_ATTEMPTS: Максимальное количество попыток (по умолчанию: 3)
FIRECRAWL_RETRY_INITIAL_DELAY: Начальная задержка в миллисекундах перед первой повторной попыткой (по умолчанию: 1000)
FIRECRAWL_RETRY_MAX_DELAY: Максимальная задержка в миллисекундах между повторными попытками (по умолчанию: 10000)
FIRECRAWL_RETRY_BACKOFF_FACTOR: Множитель экспоненциальной задержки (по умолчанию: 2)

Мониторинг использования кредитов

FIRECRAWL_CREDIT_WARNING_THRESHOLD: Порог предупреждения об использовании кредитов (по умолчанию: 1000)
FIRECRAWL_CREDIT_CRITICAL_THRESHOLD: Критический порог использования кредитов (по умолчанию: 100)

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

Для использования облачного API с пользовательскими настройками повторных попыток и мониторинга кредитов:

# Required for cloud API
export FIRECRAWL_API_KEY=your-api-key

# Optional retry configuration
export FIRECRAWL_RETRY_MAX_ATTEMPTS=5        # Increase max retry attempts
export FIRECRAWL_RETRY_INITIAL_DELAY=2000    # Start with 2s delay
export FIRECRAWL_RETRY_MAX_DELAY=30000       # Maximum 30s delay
export FIRECRAWL_RETRY_BACKOFF_FACTOR=3      # More aggressive backoff

# Optional credit monitoring
export FIRECRAWL_CREDIT_WARNING_THRESHOLD=2000    # Warning at 2000 credits
export FIRECRAWL_CREDIT_CRITICAL_THRESHOLD=500    # Critical at 500 credits

Для собственного экземпляра:

# 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

# Custom retry configuration
export FIRECRAWL_RETRY_MAX_ATTEMPTS=10
export FIRECRAWL_RETRY_INITIAL_DELAY=500     # Start with faster retries

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

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

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

        "FIRECRAWL_RETRY_MAX_ATTEMPTS": "5",
        "FIRECRAWL_RETRY_INITIAL_DELAY": "2000",
        "FIRECRAWL_RETRY_MAX_DELAY": "30000",
        "FIRECRAWL_RETRY_BACKOFF_FACTOR": "3",

        "FIRECRAWL_CREDIT_WARNING_THRESHOLD": "2000",
        "FIRECRAWL_CREDIT_CRITICAL_THRESHOLD": "500"
      }
    }
  }
}

Системная конфигурация

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

const CONFIG = {
  retry: {
    maxAttempts: 3, // Number of retry attempts for rate-limited requests
    initialDelay: 1000, // Initial delay before first retry (in milliseconds)
    maxDelay: 10000, // Maximum delay between retries (in milliseconds)
    backoffFactor: 2, // Multiplier for exponential backoff
  },
  credit: {
    warningThreshold: 1000, // Warn when credit usage reaches this level
    criticalThreshold: 100, // Critical alert when credit usage reaches this level
  },
};

Эти конфигурации управляют:

Поведением повторных попыток
- Автоматически повторяет неудачные запросы из-за ограничений частоты
- Использует экспоненциальную задержку, чтобы не перегружать API
- Пример: С настройками по умолчанию повторные попытки будут выполняться:
  - 1-я попытка: задержка 1 секунда
  - 2-я попытка: задержка 2 секунды
  - 3-я попытка: задержка 4 секунды (ограничено maxDelay)
Мониторингом использования кредитов
- Отслеживает потребление кредитов API для облачного использования
- Выдает предупреждения при достижении указанных порогов
- Помогает предотвратить неожиданное прерывание обслуживания
- Пример: С настройками по умолчанию:
  - Предупреждение при остатке 1000 кредитов
  - Критическое оповещение при остатке 100 кредитов

Ограничение частоты и пакетная обработка

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

Автоматическая обработка ограничений частоты с экспоненциальной задержкой
Эффективная параллельная обработка для пакетных операций
Интеллектуальная постановка запросов в очередь и регулирование
Автоматические повторные попытки при временных ошибках

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

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

Если вы знаете точный(е) URL:
- Для одного: используйте scrape (с форматом JSON для структурированных данных)
- Для многих: используйте batch_scrape
Если вам нужно найти URL на сайте: используйте map
Если вы хотите искать информацию в интернете: используйте search
Если вам нужно сложное исследование по множеству неизвестных источников: используйте agent
Если вы хотите проанализировать весь сайт или раздел: используйте crawl (с ограничениями!)
Если вам нужна интерактивная автоматизация браузера (клики, ввод, навигация): используйте scrape + interact

Краткая справочная таблица

Инструмент	Лучше всего для	Возвращает
scrape	Содержимое одной страницы	JSON (предпочтительно) или markdown
interact	Взаимодействие с извлеченной страницей	Результат выполнения
batch_scrape	Несколько известных URL	JSON (предпочтительно) или markdown[]
map	Обнаружение URL на сайте	URL[]
crawl	Многостраничное извлечение (с ограничениями)	markdown/html[]
search	Веб-поиск информации	results[]
agent	Сложное исследование по множеству источников	JSON (структурированные данные)

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

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

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

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

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

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

Лучше всего для:

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

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

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

Распространенные ошибки:

Использование scrape для списка URL (вместо этого используйте batch_scrape).
Использование формата 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, профиль бренда или другие форматы по указанию.

2. Инструмент Batch Scrape (`firecrawl_batch_scrape`)

Эффективное извлечение нескольких URL со встроенным ограничением частоты и параллельной обработкой.

Лучше всего для:

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

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

Обнаружения URL (сначала используйте map, если вы не знаете URL)
Извлечения одной страницы (используйте scrape)

Распространенные ошибки:

Использование batch_scrape со слишком большим количеством URL за раз (может привести к ограничению частоты или переполнению токенов)

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

"Получи содержимое этих трех блог-постов: [url1, url2, url3]."

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

{
  "name": "firecrawl_batch_scrape",
  "arguments": {
    "urls": ["https://example1.com", "https://example2.com"],
    "options": {
      "formats": ["markdown"],
      "onlyMainContent": true
    }
  }
}

Возвращает:

Ответ включает идентификатор операции для проверки статуса:

{
  "content": [
    {
      "type": "text",
      "text": "Batch operation queued with ID: batch_1. Use firecrawl_check_batch_status to check progress."
    }
  ],
  "isError": false
}

3. Проверка статуса пакета (`firecrawl_check_batch_status`)

Проверка статуса пакетной операции.

{
  "name": "firecrawl_check_batch_status",
  "arguments": {
    "id": "batch_1"
  }
}

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

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

Лучше всего для:

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

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

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

Распространенные ошибки:

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

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

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

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

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

Возвращает:

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

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

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

Лучше всего для:

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

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

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

Распространенные ошибки:

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

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

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

Возвращает:

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

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

«Найди последние научные статьи по ИИ, опубликованные в 2023 году.»

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

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

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

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

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

Дневной лимит возврата (на команду, за сутки по UTC, по умолчанию 100 кредитов). Когда creditsRefundedToday команды достигает dailyRefundCap, последующие отправки всё ещё записывают обратную связь, но больше не возвращают кредиты. Ответ устанавливает 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'"
  }
}

Возвращает:

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

5c. Универсальный инструмент обратной связи (`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?, alreadySubmitted?, warning? }.

6. Инструмент сканирования (Crawl) (`firecrawl_crawl`)

Запускает асинхронную задачу сканирования веб-сайта и извлекает контент со всех страниц.

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

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

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

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

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

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

Установка слишком высоких limit или maxDepth (вызывает переполнение токенов)
Использование crawl для одной страницы (используйте scrape)

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

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

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

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

Возвращает:

Ответ включает идентификатор операции для проверки статуса:

{
  "content": [
    {
      "type": "text",
      "text": "Started crawl for: https://example.com/* with job ID: 550e8400-e29b-41d4-a716-446655440000. Use firecrawl_check_crawl_status to check progress."
    }
  ],
  "isError": false
}

7. Проверка статуса сканирования (`firecrawl_check_crawl_status`)

Проверяет статус задачи сканирования.

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

Возвращает:

Ответ включает статус задачи сканирования:

8. Инструмент извлечения (Extract) (`firecrawl_extract`)

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

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

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

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

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

Аргументы:

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

При использовании собственного экземпляра извлечение будет использовать настроенный вами LLM. Для облачного API используется управляемый сервис LLM 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
}

9. Инструмент «Агент» (Agent) (`firecrawl_agent`)

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

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

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

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

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

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

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

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

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

Аргументы:

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

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

«Найди основателей 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, используя возвращённый идентификатор задачи.

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

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

Возвращает:

Идентификатор задачи для проверки статуса. Используйте firecrawl_agent_status для опроса результатов.

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

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

Шаблон опроса: Исследование агента может занимать минуты для сложных запросов. Опрашивайте эту конечную точку периодически (например, каждые 10–30 секунд), пока статус не станет «completed» или «failed».

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

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

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

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

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

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

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

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

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

Оценка значимых изменений выполняется автоматически, когда установлен goal. Вебхуки страниц предоставляют 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, когда вам нужны цели сканирования, отслеживание изменений в 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_checks: список проверок, опционально отфильтрованных по статусу.
firecrawl_monitor_check: получить результаты на уровне страниц, включая diff, snapshot, judgment.meaningful и judgment.meaningfulChanges.

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

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

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

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

[INFO] Firecrawl MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[INFO] Batch operation queued with ID: batch_1
[WARNING] Credit usage has reached warning threshold
[ERROR] Rate limit exceeded, retrying in 2s...

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

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

Автоматические повторные попытки при временных ошибках
Обработка ограничений скорости с отложенными повторами
Подробные сообщения об ошибках
Предупреждения об использовании кредитов
Устойчивость к сетевым проблемам

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

{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded. Retrying in 2 seconds..."
    }
  ],
  "isError": true
}

Разработка

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Участие в проекте

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

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

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

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

Лицензия

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

Firecrawl MCP Server

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

Firecrawl MCP Server

Возможности

Установка

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

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

Запуск в Cursor

Запуск в Windsurf

Запуск в локальном режиме с потоковой передачей HTTP

Установка через Smithery (устаревший способ)

Запуск в VS Code

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

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

Обязательные для облачного API

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

Дополнительная конфигурация

Конфигурация повторных попыток

Мониторинг использования кредитов

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

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

Системная конфигурация

Ограничение частоты и пакетная обработка

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

Краткая справочная таблица

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

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

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

2. Инструмент Batch Scrape (firecrawl_batch_scrape)

3. Проверка статуса пакета (firecrawl_check_batch_status)

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

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

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

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

6. Инструмент сканирования (Crawl) (firecrawl_crawl)

7. Проверка статуса сканирования (firecrawl_check_crawl_status)

8. Инструмент извлечения (Extract) (firecrawl_extract)

9. Инструмент «Агент» (Agent) (firecrawl_agent)

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

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

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

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

Разработка

Участие в проекте

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

Лицензия

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

2. Инструмент Batch Scrape (`firecrawl_batch_scrape`)

3. Проверка статуса пакета (`firecrawl_check_batch_status`)

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

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

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

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

6. Инструмент сканирования (Crawl) (`firecrawl_crawl`)

7. Проверка статуса сканирования (`firecrawl_check_crawl_status`)

8. Инструмент извлечения (Extract) (`firecrawl_extract`)

9. Инструмент «Агент» (Agent) (`firecrawl_agent`)

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

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