> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Servidor MCP do Firecrawl
> Use a API do Firecrawl por meio do Model Context Protocol
Uma implementação de servidor do Model Context Protocol (MCP) que integra o [Firecrawl](https://github.com/firecrawl/firecrawl) para busca, scraping e interagir com a web. Nosso servidor MCP é de código aberto e está disponível no [GitHub](https://github.com/firecrawl/firecrawl-mcp-server).
## Recursos
* Fazer uma busca na web e obter o conteúdo completo da página
* Fazer scraping de qualquer URL para obter dados estruturados limpos
* Processar arquivos locais, como PDFs, DOCX, XLSX e HTML
* Interagir com páginas — clicar, navegar e executar ações
* Pesquisa avançada com agente autônomo
* Suporte em nuvem e auto-hospedado
* Suporte a HTTP com streaming
## Instalação
Você pode usar nossa URL hospedada remotamente ou executar o servidor localmente. Obtenha sua chave de API em [https://firecrawl.dev/app/api-keys](https://www.firecrawl.dev/app/api-keys)
**Sem chave de API?** Conecte-se a `https://mcp.firecrawl.dev/v2/mcp` para usar o plano gratuito remoto sem chave. É gratuito e tem limite de taxa por IP; veja [limite de taxa](/pt-BR/rate-limits#keyless-no-api-key) para a lista atual de ferramentas sem chave. Defina `FIRECRAWL_API_KEY` para desbloquear todas as ferramentas do MCP e limites mais altos.
### URL hospedada remotamente
Conecte-se sem uma API key para começar no tier Free remoto sem chave (com limite de requisições por IP; consulte [Limites de taxa](/pt-BR/rate-limits#keyless-no-api-key) para a lista atual de ferramentas):
```bash theme={null}
https://mcp.firecrawl.dev/v2/mcp
```
Com uma API key, envie-a no header `Authorization` para desbloquear todas as ferramentas, além de limites maiores:
```json theme={null}
{
"mcpServers": {
"firecrawl": {
"url": "https://mcp.firecrawl.dev/v2/mcp",
"headers": {
"Authorization": "Bearer fc-YOUR_API_KEY"
}
}
}
}
```
### Executando com npx
```bash theme={null}
env FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp
```
### Instalação manual
```bash theme={null}
npm install -g firecrawl-mcp
```
### Executando no Cursor
Instale o servidor hospedado keyless com um clique (não requer API key):
Ou adicione-o manualmente ao `~/.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"firecrawl": {
"url": "https://mcp.firecrawl.dev/v2/mcp"
}
}
}
```
#### Executando localmente com uma chave de API
Observação: requer o Cursor na versão 0.45.6 ou superior.
Para obter as instruções de configuração mais atualizadas, consulte a documentação oficial do Cursor sobre como configurar servidores MCP:
[Guia de configuração de servidor MCP do Cursor](https://cursor.com/docs/context/mcp)
Para configurar o Firecrawl MCP no Cursor **v0.48.6**
1. Abra as Configurações do Cursor
2. Vá em Features > MCP Servers
3. Clique "+ Add new global MCP server"
4. Enter the following code:
```json theme={null}
{
"mcpServers": {
"firecrawl-mcp": {
"command": "npx",
"args": ["-y", "firecrawl-mcp"],
"env": {
"FIRECRAWL_API_KEY": "YOUR-API-KEY"
}
}
}
}
```
Para configurar o Firecrawl MCP no Cursor **v0.45.6**
1. Abra as Configurações do Cursor
2. Vá em Features > MCP Servers
3. Clique "+ Add New MCP Server"
4. Insira o seguinte:
* Name: "firecrawl-mcp" (ou o nome de sua preferência)
* Type: "command"
* Command: `env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp`
> Se você estiver no Windows e tiver problemas, tente `cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"`
Substitua `your-api-key` pela sua chave de API do Firecrawl. Se você ainda não tiver uma, crie uma conta e obtenha-a em [https://www.firecrawl.dev/app/api-keys](https://www.firecrawl.dev/app/api-keys)
Após adicionar, atualize a lista de servidores MCP para ver as novas ferramentas. O Composer Agent usará automaticamente o Firecrawl MCP quando apropriado, mas você pode solicitá-lo explicitamente descrevendo suas necessidades de dados da web. Acesse o Composer com Command+L (Mac), selecione "Agent" ao lado do botão de envio e insira sua consulta.
### Executando no Windsurf
Adicione isto ao arquivo `./codeium/windsurf/model_config.json`:
```json theme={null}
{
"mcpServers": {
"mcp-server-firecrawl": {
"command": "npx",
"args": ["-y", "firecrawl-mcp"],
"env": {
"FIRECRAWL_API_KEY": "SUA_API_KEY"
}
}
}
}
```
### Executando no modo HTTP com streaming
Para executar o servidor localmente usando o transporte HTTP com streaming em vez do transporte `stdio` padrão:
```bash theme={null}
env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp
```
Use a URL: [http://localhost:3000/v2/mcp](http://localhost:3000/v2/mcp) localmente ou a versão hospedada [https://mcp.firecrawl.dev/v2/mcp](https://mcp.firecrawl.dev/v2/mcp)
### Instalação via Smithery (legado)
Para instalar o Firecrawl no Claude Desktop automaticamente usando o [Smithery](https://smithery.ai/server/@mendableai/mcp-server-firecrawl):
```bash theme={null}
npx -y @smithery/cli install @mendableai/mcp-server-firecrawl --client claude
```
### Executando no VS Code
Para instalar com um clique, use um dos botões de instalação abaixo...
[](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) [](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)
Para instalação manual, adicione o seguinte bloco JSON ao arquivo User Settings (JSON) no VS Code. Você pode fazer isso pressionando `Ctrl + Shift + P` e digitando `Preferences: Open User Settings (JSON)`.
```json theme={null}
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "apiKey",
"description": "Chave de API do Firecrawl",
"password": true
}
],
"servers": {
"firecrawl": {
"command": "npx",
"args": ["-y", "firecrawl-mcp"],
"env": {
"FIRECRAWL_API_KEY": "${input:apiKey}"
}
}
}
}
}
```
Opcionalmente, você também pode adicioná-lo a um arquivo chamado `.vscode/mcp.json` no seu espaço de trabalho. Isso permitirá que você compartilhe essa configuração com outras pessoas:
```json theme={null}
{
"inputs": [
{
"type": "promptString",
"id": "apiKey",
"description": "Chave da API do Firecrawl",
"password": true
}
],
"servers": {
"firecrawl": {
"command": "npx",
"args": ["-y", "firecrawl-mcp"],
"env": {
"FIRECRAWL_API_KEY": "${input:apiKey}"
}
}
}
}
```
**Nota:** Alguns usuários relataram problemas ao adicionar o servidor MCP ao VS Code devido à forma como ele valida JSON com um formato de schema desatualizado ([microsoft/vscode#155379](https://github.com/microsoft/vscode/issues/155379)).
Isso afeta várias ferramentas MCP, incluindo Firecrawl.
**Solução alternativa:** Desative a validação de JSON no VS Code para permitir que o servidor MCP seja carregado corretamente.
Consulte a referência: [directus/directus#25906 (comment)](https://github.com/directus/directus/issues/25906#issuecomment-3369169513).
O servidor MCP continua funcionando normalmente quando invocado por outras extensões, mas o problema ocorre especificamente ao registrá-lo diretamente na lista de servidores MCP. Planejamos adicionar orientações assim que o VS Code atualizar a validação de schema.
### Executando no Claude Desktop
Adicione o seguinte ao arquivo de configuração do Claude:
```json theme={null}
{
"mcpServers": {
"firecrawl": {
"url": "https://mcp.firecrawl.dev/v2/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
Se você receber um erro "Não foi possível se conectar ao servidor MCP", sua versão do Claude Desktop pode não oferecer suporte a transporte HTTP com streaming. Use a abordagem local com npx em vez disso (requer [Node.js](https://nodejs.org)):
```json theme={null}
{
"mcpServers": {
"firecrawl": {
"command": "npx",
"args": ["-y", "firecrawl-mcp"],
"env": {
"FIRECRAWL_API_KEY": "YOUR_API_KEY"
}
}
}
}
```
Se você vir um erro `spawn npx ENOENT`, o Node.js não está instalado ou não está no PATH do sistema. Instale o Node.js em [nodejs.org](https://nodejs.org) (versão LTS) e, em seguida, reinicie completamente o Claude Desktop. No Windows, você também pode executar `where npx` no Prompt de Comando e usar o caminho completo (por exemplo, `C:\\Program Files\\nodejs\\npx.cmd`) como valor de `command`.
### Executando no Claude Code
Adicione o servidor MCP do Firecrawl usando a CLI do Claude Code. Você pode usar a URL hospedada remotamente ou executar localmente:
```bash theme={null}
# URL hospedada remotamente (recomendado, funciona sem uma API key)
claude mcp add --transport http firecrawl https://mcp.firecrawl.dev/v2/mcp
# Com uma API key, envie-a como um header de Authorization
claude mcp add --transport http firecrawl https://mcp.firecrawl.dev/v2/mcp --header "Authorization: Bearer fc-your-api-key"
# Ou execute localmente via npx
claude mcp add firecrawl -e FIRECRAWL_API_KEY=fc-your-api-key -- npx -y firecrawl-mcp
```
### Executando no Google Antigravity
O Google Antigravity permite configurar servidores MCP diretamente pela interface do Agent.
1. Abra a barra lateral do Agent no Editor ou na visualização Agent Manager
2. Clique no menu "..." (More Actions) e selecione **MCP Servers**
3. Selecione **View raw config** para abrir o arquivo local `mcp_config.json`
4. Adicione a seguinte configuração:
```json theme={null}
{
"mcpServers": {
"firecrawl": {
"command": "npx",
"args": ["-y", "firecrawl-mcp"],
"env": {
"FIRECRAWL_API_KEY": "YOUR_FIRECRAWL_API_KEY"
}
}
}
}
```
5. Salve o arquivo e clique em **Refresh** na interface Antigravity MCP para ver as novas ferramentas
Substitua `YOUR_FIRECRAWL_API_KEY` pela sua chave de API de [https://firecrawl.dev/app/api-keys](https://www.firecrawl.dev/app/api-keys).
### Executando no n8n
Para conectar o servidor MCP do Firecrawl no n8n:
1. Obtenha sua chave de API do Firecrawl em [https://firecrawl.dev/app/api-keys](https://www.firecrawl.dev/app/api-keys)
2. No seu fluxo de trabalho do n8n, adicione um nó **AI Agent**
3. Na configuração do nó AI Agent, adicione uma nova **Tool**
4. Selecione **MCP Client Tool** como o tipo de ferramenta
5. Insira o endpoint do servidor MCP:
```
https://mcp.firecrawl.dev/v2/mcp
```
6. Defina **Server Transport** como **HTTP Streamable**
7. Defina **Authentication** como **Bearer** e cole sua chave de API do Firecrawl, ou deixe como **None** para usar o plano gratuito sem chave
8. Em **Tools to include**, você pode selecionar **All**, **Selected** ou **All Except** – isso expõe as ferramentas do Firecrawl (scrape, crawl, map, search, extract, etc.)
Para implantações autohospedadas, execute o servidor MCP com npx e habilite o modo de transporte HTTP:
```bash theme={null}
env HTTP_STREAMABLE_SERVER=true \
FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
FIRECRAWL_API_URL=YOUR_FIRECRAWL_INSTANCE \
npx -y firecrawl-mcp
```
Isso iniciará o servidor em `http://localhost:3000/v2/mcp`, que você pode usar no seu workflow do n8n como endpoint. A variável de ambiente `HTTP_STREAMABLE_SERVER=true` é obrigatória, já que o n8n precisa de transporte HTTP.
## Configuração
### Variáveis de Ambiente
#### API em nuvem e auto-hospedada
* `FIRECRAWL_API_KEY`: Sua chave de API do Firecrawl
* Obrigatória ao usar a API em nuvem (padrão)
* Opcional ao usar uma instância auto-hospedada com `FIRECRAWL_API_URL`
* `FIRECRAWL_API_URL` (opcional): Endpoint de API personalizado para instâncias auto-hospedadas
* Exemplo: `https://firecrawl.seu-dominio.com`
* Se não for fornecido, a API em nuvem será usada (requer chave de API)
### Exemplos de configuração
Para uso da API em nuvem:
```bash theme={null}
export FIRECRAWL_API_KEY=your-api-key
```
Para instâncias auto-hospedadas:
```bash theme={null}
export FIRECRAWL_API_URL=https://firecrawl.your-domain.com
export FIRECRAWL_API_KEY=your-api-key # Se sua instância exigir autenticação
```
### Configuração personalizada com o Claude Desktop
Adicione o seguinte ao seu `claude_desktop_config.json`:
```json theme={null}
{
"mcpServers": {
"mcp-server-firecrawl": {
"command": "npx",
"args": ["-y", "firecrawl-mcp"],
"env": {
"FIRECRAWL_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
```
### MCP hospedado vs MCP local
O servidor MCP hospedado é otimizado para uso remoto seguro. Algumas opções disponíveis ao executar o servidor MCP localmente são limitadas ou indisponíveis no uso remoto:
* O modo keyless hospedado expõe apenas as ferramentas compatíveis com keyless e está sujeito a limite de taxa por IP.
* A leitura de arquivos locais só está disponível quando você executa o servidor MCP localmente.
* Webhooks e caminhos de arquivos locais devem ser configurados a partir de um servidor MCP local ou auto-hospedado quando o agente precisar de acesso a recursos locais.
### Limites de taxa
Os limites de taxa são aplicados pelo Firecrawl. Use uma chave de API para ter limites mais altos e acesso ao conjunto completo de ferramentas.
## Ferramentas disponíveis
### 1. Ferramenta de scraping (`firecrawl_scrape`)
Extraia conteúdo de uma única URL com opções avançadas.
```json theme={null}
{
"name": "firecrawl_scrape",
"arguments": {
"url": "https://example.com",
"formats": ["markdown"],
"onlyMainContent": true,
"waitFor": 1000,
"mobile": false,
"includeTags": ["article", "main"],
"excludeTags": ["nav", "footer"],
"skipTlsVerification": false
}
}
```
Para ocultar informações de identificação pessoal, inclua `redactPII` nos argumentos da ferramenta de scraping.
```json theme={null}
{
"name": "firecrawl_scrape",
"arguments": {
"url": "https://example.com/contact",
"formats": ["markdown"],
"redactPII": true
}
}
```
### 2. Ferramenta de Mapeamento (`firecrawl_map`)
Mapeie um site para descobrir todas as URLs indexadas do site.
```json theme={null}
{
"name": "firecrawl_map",
"arguments": {
"url": "https://example.com",
"search": "blog",
"sitemap": "include",
"includeSubdomains": false,
"limit": 100,
"ignoreQueryParameters": true
}
}
```
#### Opções da ferramenta Map:
* `url`: A URL base do site a ser mapeado
* `search`: Termo de pesquisa opcional para filtrar URLs
* `sitemap`: Controla o uso do sitemap — "include", "skip" ou "only"
* `includeSubdomains`: Se deve incluir subdomínios no mapeamento
* `limit`: Número máximo de URLs a serem retornadas
* `ignoreQueryParameters`: Se deve ignorar parâmetros de consulta ao mapear
**Ideal para:** Descobrir URLs em um site antes de decidir o que extrair; encontrar seções específicas de um site.
**Retorna:** Array de URLs encontradas no site.
### 3. Search Tool (`firecrawl_search`)
Pesquise na web e, opcionalmente, extraia conteúdo dos resultados da busca.
```json theme={null}
{
"name": "firecrawl_search",
"arguments": {
"query": "sua consulta de busca",
"limit": 5,
"location": "United States",
"tbs": "qdr:m",
"scrapeOptions": {
"formats": ["markdown"],
"onlyMainContent": true
}
}
}
```
#### Opções da Search Tool:
* `query`: A string da consulta de busca (obrigatório)
* `limit`: Número máximo de resultados a serem retornados
* `location`: Localização geográfica para os resultados de busca
* `tbs`: Filtro de busca baseado em tempo (por exemplo, `qdr:d` para o último dia, `qdr:w` para a última semana, `qdr:m` para o último mês)
* `filter`: Filtro adicional de busca
* `sources`: Array de tipos de fonte a serem pesquisados (`web`, `images`, `news`)
* `scrapeOptions`: Opções para scraping das páginas de resultados de busca
* `enterprise`: Array de opções de enterprise (`default`, `anon`, `zdr`)
### 4. Ferramenta Parse (`firecrawl_parse`)
Converta um arquivo local, como um documento PDF, DOCX, XLSX ou HTML, em dados limpos e prontos para LLM.
```json theme={null}
{
"name": "firecrawl_parse",
"arguments": {
"filePath": "/absolute/path/to/report.pdf",
"formats": ["markdown"]
}
}
```
Quando você executa o Firecrawl MCP localmente em uma instância da API do Firecrawl com `FIRECRAWL_API_URL`, o servidor MCP pode ler `filePath` diretamente e envia os bytes do arquivo para `/v2/parse`.
Quando você usa o servidor MCP remoto hospedado, o servidor hospedado não consegue ler arquivos da sua máquina. Nesse caso, `firecrawl_parse` usa um fluxo em duas etapas que também funciona na URL remota sem chave:
1. Chame `firecrawl_parse` com `filePath`. A ferramenta retorna um comando de upload pré-preenchido e um `nextToolCall` contendo um `uploadRef`.
2. Execute o comando de upload na máquina que consegue ler o arquivo e, em seguida, chame `firecrawl_parse` novamente com o `uploadRef` retornado.
O comando de upload envia os bytes do arquivo para um destino de upload assinado com validade curta. Ele não inclui sua chave de API do Firecrawl.
#### Opções da ferramenta Parse:
* `filePath`: Caminho local para o arquivo que você quer analisar. Use isto na primeira chamada.
* `uploadRef`: Referência retornada pela primeira chamada ao hosted-MCP. Use isto na segunda chamada, depois que o upload for concluído com sucesso.
* `formats`: Formatos de resultado. O padrão é `markdown`.
* `parsers`: Controles do parser, como opções de análise de PDF.
* `contentType`: Substituição opcional do tipo MIME do arquivo.
* `declaredSizeBytes`: Indicação opcional do tamanho do arquivo. Os arquivos têm limite de 50 MB.
**Ideal para:** Documentos locais ou não públicos que não estejam disponíveis em uma URL pública.
**Não recomendado para:** URLs públicas de documentos. Use `firecrawl_scrape` em vez disso; ele detectará e analisará documentos a partir de URLs.
### 5. Ferramenta de Rastreamento (`firecrawl_crawl`)
Inicia um rastreamento assíncrono com opções avançadas.
```json theme={null}
{
"name": "firecrawl_crawl",
"arguments": {
"url": "https://example.com",
"maxDiscoveryDepth": 2,
"limit": 100,
"allowExternalLinks": false,
"deduplicateSimilarURLs": true
}
}
```
### 6. Verificar status do rastreamento (`firecrawl_check_crawl_status`)
Verifique o status de um job de rastreamento.
```json theme={null}
{
"name": "firecrawl_check_crawl_status",
"arguments": {
"id": "550e8400-e29b-41d4-a716-446655440000"
}
}
```
**Retorna:** Status e progresso do job de rastreamento, incluindo os resultados, se disponíveis.
Extraia informações estruturadas de páginas da web usando LLMs. Suporta extração tanto com IA em nuvem quanto com LLMs auto-hospedados.
```json theme={null}
{
"name": "firecrawl_extract",
"arguments": {
"urls": ["https://example.com/page1", "https://example.com/page2"],
"prompt": "Extract product information including name, price, and description",
"schema": {
"type": "object",
"properties": {
"name": { "type": "string" },
"price": { "type": "number" },
"description": { "type": "string" }
},
"required": ["name", "price"]
},
"allowExternalLinks": false,
"enableWebSearch": false,
"includeSubdomains": false
}
}
```
Exemplo de resposta:
```json theme={null}
{
"content": [
{
"type": "text",
"text": {
"name": "Example Product",
"price": 99.99,
"description": "This is an example product description"
}
}
],
"isError": false
}
```
* `urls`: Array de URLs das quais extrair informações
* `prompt`: Prompt personalizado para a extração pelo LLM
* `schema`: Esquema JSON para extração de dados estruturados
* `allowExternalLinks`: Permite extração a partir de links externos
* `enableWebSearch`: Habilita busca na web para contexto adicional
* `includeSubdomains`: Inclui subdomínios na extração
Ao usar uma instância auto-hospedada, a extração usará o LLM que você configurou. Na API em nuvem, ela usa o serviço de LLM gerenciado do Firecrawl.
### 8. Agent Tool (`firecrawl_agent`)
Agente autônomo de pesquisa na web que navega independentemente pela internet, busca informações, percorre páginas e extrai dados estruturados com base na sua consulta. Esse agente é executado de forma assíncrona — ele retorna imediatamente um ID de job, e você faz polling em `firecrawl_agent_status` para verificar quando for concluído e recuperar os resultados.
```json theme={null}
{
"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" }
}
}
}
}
}
}
}
```
Você também pode fornecer URLs específicas nas quais o agente deve se concentrar:
```json theme={null}
{
"name": "firecrawl_agent",
"arguments": {
"urls": ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
"prompt": "Compare the features and pricing information from these pages"
}
}
```
#### Opções da ferramenta de agente:
* `prompt`: Descrição em linguagem natural dos dados que você quer (obrigatório, máx. 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
**Melhor para:** Tarefas de pesquisa complexas quando você não sabe as URLs exatas; coleta de dados de múltiplas fontes; encontrar informações espalhadas pela web; extrair dados de SPAs pesadas em JavaScript que falham com a raspagem comum.
**Retorna:** ID do job para verificação de status. Use `firecrawl_agent_status` para consultar os resultados periodicamente.
### 9. Verificar status do agente (`firecrawl_agent_status`)
Verifique o status de um job do agente e recupere os resultados quando ela for concluída. Faça verificações (polling) a cada 15–30 segundos e mantenha por pelo menos 2–3 minutos antes de considerar a solicitação como falha.
```json theme={null}
{
"name": "firecrawl_agent_status",
"arguments": {
"id": "550e8400-e29b-41d4-a716-446655440000"
}
}
```
#### Opções de status do agente:
* `id`: O ID da tarefa do agente retornado por `firecrawl_agent` (obrigatório)
**Possíveis status:**
* `processing`: O agente ainda está pesquisando — continue consultando periodicamente
* `completed`: Pesquisa concluída — a resposta inclui os dados extraídos
* `failed`: Ocorreu um erro
**Retorna:** Status, progresso e resultados (se concluída) da tarefa do agente.
### 10. Interagir com uma página (`firecrawl_interact`)
Interaja com uma página em uma sessão ativa no navegador: clique em botões, preencha formulários, extraia conteúdo dinâmico ou navegue mais a fundo.
Use um dos dois modos de direcionamento:
* Passe `url` para abrir e interagir com uma nova página em uma única chamada MCP.
* Passe `scrapeId` de uma chamada anterior de `firecrawl_scrape` para reutilizar a página já carregada.
Não passe `url` e `scrapeId` ao mesmo tempo. Forneça `prompt` ou `code`. `scrapeOptions` só pode ser usado no modo `url`.
**Exemplo de modo URL:**
```json theme={null}
{
"name": "firecrawl_interact",
"arguments": {
"url": "https://example.com/products",
"prompt": "Click on the first product and tell me its price"
}
}
```
**Exemplo de reutilização do scraping:**
```json theme={null}
{
"name": "firecrawl_interact",
"arguments": {
"scrapeId": "scrape-id-from-previous-scrape",
"prompt": "Click the Sign In button"
}
}
```
#### Opções da ferramenta Interact:
* `url`: Página com a qual interagir; abre a sessão para você. Use isto ou `scrapeId`.
* `scrapeId`: O ID do job de scraping de uma chamada anterior a `firecrawl_scrape`. Use isto ou `url`.
* `prompt`: Instrução em linguagem natural que descreve a ação a ser executada. Forneça `prompt` ou `code`.
* `code`: Código a ser executado na sessão do navegador. Forneça `code` ou `prompt`.
* `language`: `bash`, `python` ou `node` (opcional, o padrão é `node`, usado apenas com `code`).
* `timeout`: Tempo limite de execução em segundos, de 1 a 300 (opcional, o padrão é 30).
* `scrapeOptions`: Controles opcionais de scraping usados apenas no modo `url`.
**Ideal para:** Fluxos de trabalho com várias etapas em uma única página — pesquisar em um site, clicar nos resultados, preencher formulários e extrair dados que exigem interação.
**Retorna:** Resultado da interação, incluindo o resultado e URLs de visualização em tempo real.
### 11. Encerrar sessão de interação (`firecrawl_interact_stop`)
Encerre uma sessão de interação de uma página extraída. Use isso quando terminar de interagir para liberar recursos.
```json theme={null}
{
"name": "firecrawl_interact_stop",
"arguments": {
"scrapeId": "scrape-id-from-previous-scrape"
}
}
```
#### Opções para interromper a interação:
* `scrapeId`: O ID do scraping da sessão a ser interrompida (obrigatório)
**Retorna:** Confirmação de que a sessão foi interrompida.
## Sistema de Log
O servidor inclui registros abrangentes:
* Status e progresso da operação
* Métricas de desempenho
* Monitoramento do uso de créditos
* Acompanhamento de limites de taxa
* Condições de erro
Exemplos de mensagens de log:
```
[INFO] Firecrawl MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[INFO] Starting crawl for URL: https://example.com
[WARNING] Credit usage has reached warning threshold
[ERROR] Limite de requisições excedido, tentando novamente em 2s...
```
## Tratamento de Erros
O servidor oferece um tratamento de erros robusto:
* Novas tentativas automáticas para erros transitórios
* Tratamento de rate limit com backoff
* Mensagens de erro detalhadas
* Alertas de uso de créditos
* Resiliência de rede
Exemplo de resposta de erro:
```json theme={null}
{
"content": [
{
"type": "text",
"text": "Error: Rate limit exceeded. Retrying in 2 seconds..."
}
],
"isError": true
}
```
## Desenvolvimento
```bash theme={null}
# Instalar dependências
npm install
# Build
npm run build
# Executar testes
npm test
```
### Contribuindo
1. Faça um fork do repositório
2. Crie uma branch para sua feature
3. Execute os testes: `npm test`
4. Envie um pull request
### Agradecimentos aos colaboradores
Obrigado a [@vrknetha](https://github.com/vrknetha) e [@cawstudios](https://caw.tech) pela implementação inicial!
Obrigado à MCP.so e à Klavis AI pela hospedagem, e a [@gstarwd](https://github.com/gstarwd), [@xiangkaiz](https://github.com/xiangkaiz) e [@zihaolin96](https://github.com/zihaolin96) por integrarem nosso servidor.
## Licença
Licença MIT — consulte o arquivo LICENSE para mais detalhes