Na camada gratuita sem chave, `scrape`, `search` e `interact` funcionam sem uma API key (com limite de taxa). Outras ferramentas como `crawl`, `map`, `agent` e `extract` ainda precisam de uma chave.

Prefira uma API key ou OAuth sempre que o usuário puder se inscrever. Isso desbloqueia o conjunto completo de ferramentas e limites mais altos. Com uma chave, use:```
https://mcp.firecrawl.dev/{FIRECRAWL_API_KEY}/v2/mcp

### Instalação Manual```bash
npm install -g firecrawl-mcp

{
  "models": {
    "Firecrawl MCP": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "your-api-key-here"
      }
    }
  }
}
``````json
{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Use o URL: http://localhost:3000/mcp

### Instalando via Smithery (Legado)

Para instalar o Firecrawl para o Claude Desktop automaticamente via [Smithery](https://smithery.ai/server/@mendableai/mcp-server-firecrawl):```bash
npx -y @smithery/cli install @mendableai/mcp-server-firecrawl --client claude

Opcionalmente, você pode adicioná-lo a um arquivo chamado `.vscode/mcp.json` no seu espaço de trabalho. Isso permitirá que você compartilhe a configuração com outros:

```json
{
  "mcpServers": {
    ...
  }
}
``````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}"
      }
    }
  }
}

Para instância self-hosted:```bash
# 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

## Como Escolher uma Ferramenta

Use este guia para selecionar a ferramenta certa para sua tarefa:

- **Se você sabe a URL exata que deseja:** use **scrape** (com formato JSON para dados estruturados)
- **Se você tem múltiplas URLs conhecidas:** chame **scrape** para cada URL. Se você precisar especificamente de uma operação em lote da API, use o endpoint de lote da API Firecrawl fora do MCP.
- **Se você precisa descobrir URLs em um site:** use **map**
- **Se você deseja pesquisar na web por informações:** use **search**
- **Se você precisa de pesquisa complexa em múltiplas fontes desconhecidas:** use **agent**
- **Se você quer analisar um site inteiro ou seção:** use **crawl** (com limites!)
- **Se você precisa de automação interativa do navegador** (clicar, digitar, navegar): use **interact** com uma URL para uma página nova, ou **scrape** + **interact** quando você já extraiu a página ou precisa de um controle mais fino da extração

### Tabela de Referência Rápida

| Ferramenta   | Melhor para                                     | Retorna                        |
| ------------ | ----------------------------------------------- | ------------------------------ |
| scrape       | Conteúdo de página única                        | JSON (preferido) ou markdown   |
| interact     | Interagir com uma URL ou página extraída        | Resultado da execução + scrapeId para modo URL |
| map          | Descobrir URLs em um site                       | URL[]                          |
| crawl        | Extração de múltiplas páginas (com limites)     | status/dados finais do crawl após polling interno |
| parse        | Arquivos e referências de upload hospedado      | markdown, JSON, ou saída de documento |
| extract      | Extração estruturada de URLs                    | Dados estruturados JSON        |
| search       | Pesquisa na web por informações                 | resultados[]                   |
| agent        | Pesquisa complexa em múltiplas fontes           | JSON (dados estruturados)      |
| monitor      | Verificações recorrentes de páginas             | metadados e diffs do monitor/check |
| research     | Pesquisa em artigos e repositórios GitHub       | resultados da pesquisa e correspondências de repositórios |

### Guia de Seleção de Formato

Ao usar `scrape`, escolha o formato correto:

- **Formato JSON (recomendado para a maioria dos casos):** Use quando precisar de dados específicos de uma página. Defina um esquema baseado no que precisa extrair. Isso mantém as respostas pequenas e evita o estouro do contexto.
- **Formato Markdown (use com moderação):** Apenas quando você realmente precisa do conteúdo completo da página, como ler um artigo inteiro para resumo ou analisar a estrutura da página.

## Ferramentas Disponíveis

### 1. Ferramenta Scrape (`firecrawl_scrape`)

Extrai conteúdo de uma única URL com opções avançadas.

**Melhor para:**

- Extração de conteúdo de página única, quando você sabe exatamente qual página contém as informações.

**Não recomendado para:**

- Extrair conteúdo de múltiplas páginas (use chamadas repetidas de scrape para URLs conhecidas, ou map + scrape para descobrir URLs primeiro, ou crawl para conteúdo completo da página)
- Quando você não tem certeza de qual página contém as informações (use search)

**Erros comuns:**

- Passar uma lista de URLs para uma única chamada de scrape. Chame scrape uma vez por URL no MCP. Se você precisar especificamente de uma operação em lote da API, use o endpoint de lote da API Firecrawl fora do MCP.
- Usar formato markdown por padrão (use formato JSON para extrair apenas o que precisa).

**Escolhendo o formato correto:**

- **Formato JSON (preferido):** Na maioria dos casos, use formato JSON com um esquema para extrair apenas os dados específicos necessários. Isso mantém as respostas focadas e evita o estouro do contexto.
- **Formato Markdown:** Apenas quando a tarefa realmente requer o conteúdo completo da página (por exemplo, resumir um artigo inteiro, analisar a estrutura da página).

**Exemplo de Prompt:**

> "Obtenha os detalhes do produto de https://example.com/product."

**Exemplo de Uso (formato JSON - preferido):**```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"]
        }
      }
    ]
  }
}

**Exemplo de Uso (formato de branding - extrair identidade de marca):**```json
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com",
    "formats": ["branding"]
  }
}

**Retorna:**

- Array de URLs encontradas no site

### 3. Ferramenta de Pesquisa (`firecrawl_search`)

Pesquise na web e opcionalmente extraia conteúdo dos resultados da pesquisa.

**Melhor para:**

- Encontrar informações específicas em vários sites, quando você não sabe qual site possui a informação.
- Quando você precisa do conteúdo mais relevante para uma consulta

**Não recomendado para:**

- Quando você já sabe qual site raspar (use scrape)
- Quando você precisa de cobertura abrangente de um único site (use map ou crawl)

**Erros comuns:**

- Usar crawl ou map para perguntas abertas (use search em vez disso)

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

**Retorna:**

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

### 3c. Ferramenta de Feedback Genérica (`firecrawl_feedback`)

Envia feedback estruturado para um trabalho de endpoint v2 concluído através de `/v2/feedback`.
Use isso para feedback no nível do endpoint em trabalhos de `scrape`, `parse`, `map` ou `search`.
Para qualidade de resultados de busca especificamente, prefira `firecrawl_search_feedback` porque inclui orientação específica de busca.

Mantenha o feedback conciso: use códigos de problema, tags, notas curtas, URLs, números de página e pequenos objetos de metadados. Não inclua saídas brutas de scrape/parse.

**Opt out:** defina `FIRECRAWL_NO_ENDPOINT_FEEDBACK=1` (ou `FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1`) no ambiente ao iniciar o servidor MCP. A ferramenta `firecrawl_feedback` não será registrada, então os agentes não poderão chamá-la.

**Exemplo de Uso:**```json
{
  "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"
    }
  }
}

### 5. Verificar Status de Crawl (`firecrawl_check_crawl_status`)

Verifique o status e os resultados de um trabalho de crawl existente pelo ID.

**Retorna:**

- Status final do crawl e dados após a consulta interna, incluindo `id`, `status`, `completed`, `total`, `creditsUsed`, `expiresAt`, `next` e `data`. Use o `id` retornado com `firecrawl_check_crawl_status` se precisar verificar novamente o trabalho mais tarde.```json
{
  "name": "firecrawl_check_crawl_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

**Retorna:** Conteúdo do documento analisado ou instruções de upload hospedado com um `nextToolCall`.

### 7. Ferramenta Extract (`firecrawl_extract`)

Extraia informações estruturadas de páginas da web usando capacidades de LLM. Suporta extração via IA em nuvem e LLM auto-hospedado.

**Melhor para:**

- Extrair dados estruturados específicos como preços, nomes, detalhes.

**Não recomendado para:**

- Quando você precisa do conteúdo completo de uma página (use scrape)
- Quando você não está procurando dados estruturados específicos

**Argumentos:**

- `urls`: Array de URLs para extrair informações
- `prompt`: Prompt personalizado para a extração com LLM
- `systemPrompt`: Prompt do sistema para guiar o LLM
- `schema`: Esquema JSON para extração de dados estruturados
- `allowExternalLinks`: Permitir extração de links externos
- `enableWebSearch`: Ativar pesquisa na web para contexto adicional
- `includeSubdomains`: Incluir subdomínios na extração

Ao usar uma instância auto-hospedada, a extração usará seu LLM configurado. Para a API em nuvem, usa o serviço gerenciado de LLM do Firecrawl.

**Exemplo de Prompt:**

> "Extraia o nome do produto, preço e descrição dessas páginas de produto."

**Exemplo de Uso:**```json
{
  "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
  }
}

### 8. Ferramenta de Agente (`firecrawl_agent`)

Agente de pesquisa web autônomo. Esta é uma camada de agente de IA separada que navega independentemente pela internet, busca informações, percorre páginas e extrai dados estruturados com base na sua consulta.

**Como funciona:**

O agente realiza pesquisas na web, segue links, lê páginas e coleta dados de forma autônoma. Isso é executado **assincronamente** - ele retorna um ID de job imediatamente, e você consulta `firecrawl_agent_status` para verificar quando estiver concluído e obter os resultados.

**Fluxo de trabalho assíncrono:**

1. Chame `firecrawl_agent` com seu prompt/esquema → retorna ID do job
2. Faça outro trabalho enquanto o agente pesquisa (pode levar minutos para consultas complexas)
3. Consulte `firecrawl_agent_status` com o ID do job para verificar o progresso
4. Quando o status for "completed", a resposta inclui os dados extraídos

**Melhor para:**

- Tarefas de pesquisa complexas onde você não sabe as URLs exatas
- Coleta de dados de múltiplas fontes
- Encontrar informações espalhadas pela web
- Tarefas onde você pode fazer outro trabalho enquanto espera pelos resultados

**Não recomendado para:**

- Raspagem simples de página única onde você sabe a URL (use scrape com formato JSON - mais rápido e barato)

**Argumentos:**

- `prompt`: Descrição em linguagem natural dos dados desejados (obrigatório, máximo de 10.000 caracteres)
- `urls`: Array opcional de URLs para focar o agente em páginas específicas
- `schema`: Esquema JSON opcional para saída estruturada

**Exemplo de Prompt:**

> "Encontre os fundadores da Firecrawl e suas formações"

**Exemplo de Uso (iniciar agente, depois consultar resultados):**```json
{
  "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" }
            }
          }
        }
      }
    }
  }
}

**Returns:**

- ID do trabalho para verificação de status. Use `firecrawl_agent_status` para consultar os resultados.

### 9. Verificar Status do Agente (`firecrawl_agent_status`)

Verifique o status de um job do agente e recupere os resultados quando concluído. Use isso para consultar os resultados após iniciar um agente.

**Padrão de consulta:** A pesquisa do agente pode levar minutos para consultas complexas. Consulte este endpoint periodicamente (por exemplo, a cada 10-30 segundos) até que o status seja "completed" ou "failed".```json
{
  "name": "firecrawl_agent_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

**Retorna:** Resultado da interação e, para o modo URL, o `scrapeId` derivado para acompanhamento ou limpeza.

### 11. Ferramenta Parar Interação (`firecrawl_interact_stop`)

Pare uma sessão de interação para uma página raspada quando terminar de interagir.```json
{
  "name": "firecrawl_interact_stop",
  "arguments": {
    "scrapeId": "scrape-id-here"
  }
}

**Várias páginas com webhooks:**```json
{
  "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"
  }
}

**Outras ferramentas de monitor:**

- `firecrawl_monitor_list`: lista monitores.
- `firecrawl_monitor_get`: obtém um monitor.
- `firecrawl_monitor_update`: atualiza campos incluindo `goal`, `judgeEnabled`, `webhook`, e `notification`.
- `firecrawl_monitor_run`: aciona uma verificação agora.
- `firecrawl_monitor_delete`: exclui um monitor (destrutivo; chame apenas quando o usuário pretende removê-lo).
- `firecrawl_monitor_checks`: lista verificações, opcionalmente filtradas por status.
- `firecrawl_monitor_check`: obtém resultados no nível da página, incluindo `diff`, `snapshot`, `judgment.meaningful`, e `judgment.meaningfulChanges`.

## Sistema de Logging

O servidor inclui logging abrangente:

- Status e progresso das operações
- Métricas de desempenho
- Acompanhamento de limites de taxa
- Condições de erro

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

## Desenvolvimento```bash
# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test