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

Предпочитайте API-ключ или OAuth, если человек может зарегистрироваться. Это открывает полный набор инструментов и более высокие лимиты. С ключом используйте:```
https://mcp.firecrawl.dev/{FIRECRAWL_API_KEY}/v2/mcp

### Ручная установка```bash
npm install -g firecrawl-mcp

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

Для запуска сервера с использованием Streamable HTTP локально вместо транспортного протокола stdio по умолчанию:```bash
env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp

### Запуск в VS Code

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

[![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=firecrawl&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22Firecrawl%20API%20Key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22firecrawl-mcp%22%5D%2C%22env%22%3A%7B%22FIRECRAWL_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-NPM-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=firecrawl&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22Firecrawl%20API%20Key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22firecrawl-mcp%22%5D%2C%22env%22%3A%7B%22FIRECRAWL_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D&quality=insiders)

Для ручной установки добавьте следующий блок JSON в файл User Settings (JSON) в VS Code. Для этого нажмите `Ctrl + Shift + P` и введите `Preferences: Open User Settings (JSON)`.```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}"
        }
      }
    }
  }
}

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

### Переменные среды

#### Необходимые для Cloud 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](https://firecrawl.dev). Этот MCP-сервер передаёт любые учётные данные, которые он разрешает, в API Firecrawl как `Authorization: Bearer …`.

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

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

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

Для использования облачного API:```bash
export FIRECRAWL_API_KEY=your-api-key

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

Добавьте это в ваш `claude_desktop_config.json`:```json
{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

**Пример использования (формат markdown - когда требуется полное содержание):**```json
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/article",
    "formats": ["markdown"],
    "onlyMainContent": true
  }
}

**Branding format:** Извлекает всестороннюю идентичность бренда (цвета, шрифты, типографику, отступы, логотип, компоненты интерфейса) для анализа дизайна или повторения стиля.
**Privacy:** Установите `redactPII: true`, чтобы вернуть контент с удаленной личной информацией.

**Returns:**

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

### 2. Map Tool (`firecrawl_map`)

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

**Подходит для:**

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

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

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

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

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

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

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

**Пример использования:**```json
{
  "name": "firecrawl_map",
  "arguments": {
    "url": "https://example.com"
  }
}

**Возвращает:**

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

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

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

### 3b. Инструмент обратной связи по поиску (`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-суток, когда они видят этот флаг.

**Пример использования:**```json
{
  "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'"
  }
}

**Returns:**

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

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

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

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

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

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

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

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

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

- Установка слишком большого значения limit или maxDiscoveryDepth (приводит к переполнению токенов)
- Использование обхода для одной страницы (лучше использовать scrape)

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

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

**Пример использования:**```json
{
  "name": "firecrawl_crawl",
  "arguments": {
    "url": "https://example.com/blog/*",
    "maxDiscoveryDepth": 2,
    "limit": 100,
    "allowExternalLinks": false,
    "deduplicateSimilarURLs": true
  }
}

**Возвращает:**

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

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

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

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

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

**Поток хостированного MCP:** Хостированный MCP не может напрямую читать файловую систему вызывающего. Вызовите `firecrawl_parse` с `filePath`, чтобы получить кратковременную команду загрузки и `nextToolCall`, загрузите файл локально, затем снова вызовите `firecrawl_parse` с полученным `uploadRef`. Создание URL загрузки хостированным способом требует авторизации Firecrawl или права доступа без ключа. В локальном режиме `npx firecrawl-mcp` прямое чтение файлов в настоящее время требует `FIRECRAWL_API_URL`, указывающего на самостоятельно размещенный API Firecrawl; обычный локальный сервер только с облачным ключом API не может читать и загружать файлы через этот инструмент.

**Пример использования:**```json
{
  "name": "firecrawl_parse",
  "arguments": {
    "filePath": "/absolute/path/to/document.pdf",
    "formats": ["markdown"],
    "parsers": ["pdf"],
    "zeroDataRetention": true
  }
}

**Возвращает:**

- Извлечённые структурированные данные, как определено вашей схемой```json
{
  "content": [
    {
      "type": "text",
      "text": {
        "name": "Example Product",
        "price": 99.99,
        "description": "This is an example product description"
      }
    }
  ],
  "isError": false
}

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

**Пример использования (с URL-адресами — агент фокусируется на конкретных страницах):**```json
{
  "name": "firecrawl_agent",
  "arguments": {
    "urls": ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
    "prompt": "Compare the features and pricing information from these pages"
  }
}

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

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

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

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

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

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

- Передайте `url`, чтобы парсить и открыть страницу для взаимодействия за один MCP-вызов.
- Передайте `scrapeId`, чтобы продолжить взаимодействие с уже распарсенной страницей.
- Передайте ровно один из параметров `url` или `scrapeId` плюс либо `prompt`, либо `code`.

**Пример использования:**```json
{
  "name": "firecrawl_interact",
  "arguments": {
    "url": "https://example.com",
    "prompt": "Click the pricing link and summarize the visible plans"
  }
}

### 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_*`)

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

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

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

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

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

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

Формулируйте цели как краткие инструкции монитора из 2-3 предложений. Укажите, что должно вызывать оповещение, сохраняйте любую область действия, указанную пользователем, и включайте исключения, специфичные для намерения, только если они очевидны из запроса. Общий шум, такой как пробелы, изменения только форматирования, идентификаторы запросов, параметры отслеживания, общие метаданные и нерелевантный хром страницы, уже обрабатывается оценщиком, поэтому не повторяйте это в каждой цели. Если пользователь неопределён, оставьте цель широкой; если он просит широкий мониторинг или «любые изменения», сохраните это. Если пользователь говорит, что его что-то не волнует, включите это явно.```json
{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "page": "https://example.com/pricing",
    "goal": "Alert when pricing, packaging, or launch messaging changes."
  }
}

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

Передайте `body`, когда вам нужны цели сканирования, отслеживание изменений JSON, настраиваемое хранение или явный контроль `judgeEnabled`.```json
{
  "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" }]
    }
  }
}

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

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

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

Пример ответа с ошибкой:```json
{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded"
    }
  ],
  "isError": true
}

### Вклад в проект

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

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

Спасибо [@vrknetha](https://github.com/vrknetha), [@cawstudios](https://caw.tech) за первоначальную реализацию!

Спасибо MCP.so и Klavis AI за хостинг, а также [@gstarwd](https://github.com/gstarwd), [@xiangkaiz](https://github.com/xiangkaiz) и [@zihaolin96](https://github.com/zihaolin96) за интеграцию нашего сервера.

## Лицензия

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