Firecrawl MCP Server

Instructions

Implementation Reference

• src/index.ts:408-480 (schema)

  Defines the Tool object for 'firecrawl_search' including name, description, and detailed inputSchema for search parameters and optional scraping options.

  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:1123-1169 (handler)

  Handler for firecrawl_search tool: validates args with isSearchOptions, calls client.search via withRetry, handles credits, formats SERP results with optional scraped content into text response.

        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),
              '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: results }],
              isError: false,
            };
          } catch (error) {
            const errorMessage =
              error instanceof Error
                ? error.message
                : `Search failed: ${JSON.stringify(error)}`;
            return {
              content: [{ type: 'text', text: errorMessage }],
              isError: true,
            };
          }
        }

• src/index.ts:862-874 (registration)

  Registers the firecrawl_search tool (as SEARCH_TOOL) in the list of available tools returned by ListToolsRequestSchema.

  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:658-665 (helper)

  Type guard function isSearchOptions used to validate input arguments for firecrawl_search handler.

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

• src/index.ts:561-577 (helper)

  TypeScript interface SearchOptions defining the shape of arguments expected by firecrawl_search.

  interface SearchOptions {
    query: string;
    limit?: number;
    lang?: string;
    country?: string;
    tbs?: string;
    filter?: string;
    location?: {
      country?: string;
      languages?: string[];
    };
    scrapeOptions?: {
      formats?: string[];
      onlyMainContent?: boolean;
      waitFor?: number;
    };
  }