Firecrawl MCP Server

Instructions

Implementation Reference

• src/index.ts:1387-1456 (handler)

  Handler for the firecrawl_deep_research tool. Validates input arguments and calls the Firecrawl client's deepResearch method with callbacks for logging activities and sources. Formats and returns the final analysis.

  case 'firecrawl_deep_research': {
    if (!args || typeof args !== 'object' || !('query' in args)) {
      throw new Error('Invalid arguments for firecrawl_deep_research');
    }
  
    try {
      const researchStartTime = Date.now();
      safeLog('info', `Starting deep research for query: ${args.query}`);
  
      const response = await client.deepResearch(
        args.query as string,
        {
          maxDepth: args.maxDepth as number,
          timeLimit: args.timeLimit as number,
          maxUrls: args.maxUrls as number,
          // @ts-expect-error Extended API options including origin
          origin: 'mcp-server',
        },
        // Activity callback
        (activity) => {
          safeLog(
            'info',
            `Research activity: ${activity.message} (Depth: ${activity.depth})`
          );
        },
        // Source callback
        (source) => {
          safeLog(
            'info',
            `Research source found: ${source.url}${source.title ? ` - ${source.title}` : ''}`
          );
        }
      );
  
      // Log performance metrics
      safeLog(
        'info',
        `Deep research completed in ${Date.now() - researchStartTime}ms`
      );
  
      if (!response.success) {
        throw new Error(response.error || 'Deep research failed');
      }
  
      // Format the results
      const formattedResponse = {
        finalAnalysis: response.data.finalAnalysis,
        activities: response.data.activities,
        sources: response.data.sources,
      };
  
      return {
        content: [
          {
            type: 'text',
            text: trimResponseText(formattedResponse.finalAnalysis),
          },
        ],
        isError: false,
      };
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : String(error);
      return {
        content: [{ type: 'text', text: trimResponseText(errorMessage) }],
        isError: true,
      };
    }
  }

• src/index.ts:525-551 (schema)

  Tool schema definition for firecrawl_deep_research, including name, description, and input schema for validation.

  const DEEP_RESEARCH_TOOL: Tool = {
    name: 'firecrawl_deep_research',
    description:
      'Conduct deep research on a query using web crawling, search, and AI analysis.',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'The query to research',
        },
        maxDepth: {
          type: 'number',
          description: 'Maximum depth of research iterations (1-10)',
        },
        timeLimit: {
          type: 'number',
          description: 'Time limit in seconds (30-300)',
        },
        maxUrls: {
          type: 'number',
          description: 'Maximum number of URLs to analyze (1-1000)',
        },
      },
      required: ['query'],
    },
  };

• src/index.ts:960-973 (registration)

  Registration of the firecrawl_deep_research tool (as DEEP_RESEARCH_TOOL) in the listTools request 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,
      GENERATE_LLMSTXT_TOOL,
    ],
  }));