Firecrawl MCP Server

Instructions

Implementation Reference

• src/index.ts:1171-1272 (handler)

  Handler for the 'firecrawl_extract' tool. Validates input using isExtractOptions, calls the Firecrawl client's extract method with parameters, handles responses, credits, logging, and errors including special handling for self-hosted instances.

  case 'firecrawl_extract': {
    if (!isExtractOptions(args)) {
      throw new Error('Invalid arguments for firecrawl_extract');
    }
  
    try {
      const extractStartTime = Date.now();
  
      server.sendLoggingMessage({
        level: 'info',
        data: `Starting extraction for URLs: ${args.urls.join(', ')}`,
      });
  
      // Log if using self-hosted instance
      if (FIRECRAWL_API_URL) {
        server.sendLoggingMessage({
          level: 'info',
          data: '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;
  
      // Monitor credits for cloud API
      if (!FIRECRAWL_API_URL && hasCredits(response)) {
        await updateCreditUsage(response.creditsUsed || 0);
      }
  
      // Log performance metrics
      server.sendLoggingMessage({
        level: 'info',
        data: `Extraction completed in ${Date.now() - extractStartTime}ms`,
      });
  
      // Add warning to response if present
      const result = {
        content: [
          {
            type: 'text',
            text: JSON.stringify(response.data, null, 2),
          },
        ],
        isError: false,
      };
  
      if (response.warning) {
        server.sendLoggingMessage({
          level: 'warning',
          data: 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')
      ) {
        server.sendLoggingMessage({
          level: 'error',
          data: 'Extraction is not supported by this self-hosted instance',
        });
        return {
          content: [
            {
              type: 'text',
              text: 'Extraction is not supported by this self-hosted instance. Please ensure LLM support is configured.',
            },
          ],
          isError: true,
        };
      }
  
      return {
        content: [{ type: 'text', text: errorMessage }],
        isError: true,
      };
    }
  }

• src/index.ts:482-522 (schema)

  Tool schema definition for 'firecrawl_extract' including name, description, and detailed inputSchema with properties for URLs, prompts, schema, and extraction options.

  const EXTRACT_TOOL: Tool = {
    name: 'firecrawl_extract',
    description:
      'Extract structured information from web pages using LLM. ' +
      'Supports both cloud AI and self-hosted LLM extraction.',
    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:862-874 (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,
      BATCH_SCRAPE_TOOL,
      CHECK_BATCH_STATUS_TOOL,
      CHECK_CRAWL_STATUS_TOOL,
      SEARCH_TOOL,
      EXTRACT_TOOL,
      DEEP_RESEARCH_TOOL,
    ],
  }));

• src/index.ts:667-674 (helper)

  Type guard helper function used to validate arguments for the firecrawl_extract tool.

  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')
    );
  }