firecrawl_search

Instructions

Implementation Reference

• src/index.ts:1239-1286 (handler)

  Handler function that executes the firecrawl_search tool: validates input using isSearchOptions, calls Firecrawl client.search API, handles credits and errors, formats search results (URL, title, description, optional markdown content).

        case 'firecrawl_search': {
          if (!isSearchOptions(args)) {
            throw new Error('Invalid arguments for firecrawl_search');
          }
          try {
            const response = await withRetry(
              async () =>
                client.search(args.query, { ...args, origin: 'mcp-server' }),
              'search operation'
            );
  
            if (!response.success) {
              throw new Error(
                `Search failed: ${response.error || 'Unknown error'}`
              );
            }
  
            // Monitor credits for cloud API
            if (!FIRECRAWL_API_URL && hasCredits(response)) {
              await updateCreditUsage(response.creditsUsed);
            }
  
            // Format the results
            const results = response.data
              .map(
                (result) =>
                  `URL: ${result.url}
  Title: ${result.title || 'No title'}
  Description: ${result.description || 'No description'}
  ${result.markdown ? `\nContent:\n${result.markdown}` : ''}`
              )
              .join('\n\n');
  
            return {
              content: [{ type: 'text', text: trimResponseText(results) }],
              isError: false,
            };
          } catch (error) {
            const errorMessage =
              error instanceof Error
                ? error.message
                : `Search failed: ${JSON.stringify(error)}`;
            return {
              content: [{ type: 'text', text: trimResponseText(errorMessage) }],
              isError: true,
            };
          }
        }

• src/index.ts:409-481 (schema)

  Tool definition including name, description, and detailed inputSchema for firecrawl_search parameters like query, limit, lang, country, scrapeOptions etc.

  const SEARCH_TOOL: Tool = {
    name: 'firecrawl_search',
    description:
      'Search and retrieve content from web pages with optional scraping. ' +
      'Returns SERP results by default (url, title, description) or full page content when scrapeOptions are provided.',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query string',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results to return (default: 5)',
        },
        lang: {
          type: 'string',
          description: 'Language code for search results (default: en)',
        },
        country: {
          type: 'string',
          description: 'Country code for search results (default: us)',
        },
        tbs: {
          type: 'string',
          description: 'Time-based search filter',
        },
        filter: {
          type: 'string',
          description: 'Search filter',
        },
        location: {
          type: 'object',
          properties: {
            country: {
              type: 'string',
              description: 'Country code for geolocation',
            },
            languages: {
              type: 'array',
              items: { type: 'string' },
              description: 'Language codes for content',
            },
          },
          description: 'Location settings for search',
        },
        scrapeOptions: {
          type: 'object',
          properties: {
            formats: {
              type: 'array',
              items: {
                type: 'string',
                enum: ['markdown', 'html', 'rawHtml'],
              },
              description: 'Content formats to extract from search results',
            },
            onlyMainContent: {
              type: 'boolean',
              description: 'Extract only the main content from results',
            },
            waitFor: {
              type: 'number',
              description: 'Time in milliseconds to wait for dynamic content',
            },
          },
          description: 'Options for scraping search results',
        },
      },
      required: ['query'],
    },
  };

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

  Registers SEARCH_TOOL (firecrawl_search) in the listToolsRequestHandler, making it available to MCP clients.

  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,
    ],
  }));

• src/index.ts:729-736 (helper)

  Type guard helper to validate if arguments match SearchOptions interface for firecrawl_search.

  function isSearchOptions(args: unknown): args is SearchOptions {
    return (
      typeof args === 'object' &&
      args !== null &&
      'query' in args &&
      typeof (args as { query: unknown }).query === 'string'
    );
  }