Firecrawl MCP Server

Instructions

Implementation Reference

• src/index.ts:1195-1287 (handler)

  The handler logic for executing the firecrawl_extract tool. It validates the arguments, calls the Firecrawl client's extract method with retry logic, formats the response, and handles errors including self-hosted limitations.
  case 'firecrawl_extract': { if (!isExtractOptions(args)) { throw new Error('Invalid arguments for firecrawl_extract'); } try { const extractStartTime = Date.now(); safeLog( 'info', `Starting extraction for URLs: ${args.urls.join(', ')}` ); // Log if using self-hosted instance if (FIRECRAWL_API_URL) { safeLog('info', 'Using self-hosted instance for extraction'); } const extractResponse = await withRetry( async () => client.extract(args.urls, { prompt: args.prompt, systemPrompt: args.systemPrompt, schema: args.schema, allowExternalLinks: args.allowExternalLinks, enableWebSearch: args.enableWebSearch, includeSubdomains: args.includeSubdomains, origin: 'mcp-server', } as ExtractParams), 'extract operation' ); // Type guard for successful response if (!('success' in extractResponse) || !extractResponse.success) { throw new Error(extractResponse.error || 'Extraction failed'); } const response = extractResponse as ExtractResponse; // Log performance metrics safeLog( 'info', `Extraction completed in ${Date.now() - extractStartTime}ms` ); // Add warning to response if present const result = { content: [ { type: 'text', text: trimResponseText(JSON.stringify(response.data, null, 2)), }, ], isError: false, }; if (response.warning) { safeLog('warning', response.warning); } return result; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); // Special handling for self-hosted instance errors if ( FIRECRAWL_API_URL && errorMessage.toLowerCase().includes('not supported') ) { safeLog( 'error', 'Extraction is not supported by this self-hosted instance' ); return { content: [ { type: 'text', text: trimResponseText( 'Extraction is not supported by this self-hosted instance. Please ensure LLM support is configured.' ), }, ], isError: true, }; } return { content: [{ type: 'text', text: trimResponseText(errorMessage) }], isError: true, }; } }
• src/index.ts:504-580 (schema)

  Tool definition for firecrawl_extract, including name, detailed description, and inputSchema specifying parameters like urls (required), prompt, systemPrompt, schema, etc.
  const EXTRACT_TOOL: Tool = { name: 'firecrawl_extract', description: ` Extract structured information from web pages using LLM capabilities. Supports both cloud AI and self-hosted LLM extraction. **Best for:** Extracting specific structured data like prices, names, details. **Not recommended for:** When you need the full content of a page (use scrape); when you're not looking for specific structured data. **Arguments:** - urls: Array of URLs to extract information from - prompt: Custom prompt for the LLM extraction - systemPrompt: System prompt to guide the LLM - schema: JSON schema for structured data extraction - allowExternalLinks: Allow extraction from external links - enableWebSearch: Enable web search for additional context - includeSubdomains: Include subdomains in extraction **Prompt Example:** "Extract the product name, price, and description from these product pages." **Usage Example:** \`\`\`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 } } \`\`\` **Returns:** Extracted structured data as defined by your schema. `, inputSchema: { type: 'object', properties: { urls: { type: 'array', items: { type: 'string' }, description: 'List of URLs to extract information from', }, prompt: { type: 'string', description: 'Prompt for the LLM extraction', }, systemPrompt: { type: 'string', description: 'System prompt for LLM extraction', }, schema: { type: 'object', description: 'JSON schema for structured data extraction', }, allowExternalLinks: { type: 'boolean', description: 'Allow extraction from external links', }, enableWebSearch: { type: 'boolean', description: 'Enable web search for additional context', }, includeSubdomains: { type: 'boolean', description: 'Include subdomains in extraction', }, }, required: ['urls'], }, };
• src/index.ts:955-966 (registration)

  Registration of the firecrawl_extract tool (as EXTRACT_TOOL) in the list of available tools returned by ListToolsRequestSchema handler.
  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ SCRAPE_TOOL, MAP_TOOL, CRAWL_TOOL, CHECK_CRAWL_STATUS_TOOL, SEARCH_TOOL, EXTRACT_TOOL, DEEP_RESEARCH_TOOL, GENERATE_LLMSTXT_TOOL, ], }));
• src/index.ts:823-831 (helper)

  Type guard helper function to validate that arguments for firecrawl_extract contain a valid array of string URLs.
  function isExtractOptions(args: unknown): args is ExtractArgs { if (typeof args !== 'object' || args === null) return false; const { urls } = args as { urls?: unknown }; return ( Array.isArray(urls) && urls.every((url): url is string => typeof url === 'string') ); }