Firecrawl MCP Server

Instructions

Implementation Reference

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

  The main handler function for the 'firecrawl_search' tool. It validates input using isSearchOptions, calls the Firecrawl client's search method with retry logic, formats the search results (URL, title, description, optional markdown content), handles credits, and returns formatted text 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)

  The Tool definition for 'firecrawl_search' including name, description, and detailed inputSchema specifying parameters like query (required), limit, lang, country, scrapeOptions for optional scraping of results.
  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-972 (registration)

  Registration of all tools including SEARCH_TOOL in the ListToolsRequestHandler response.
  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 function to validate arguments for the firecrawl_search tool.
  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:629-649 (helper)

  TypeScript interface defining the expected input parameters for the search tool, used in validation.
  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; includeTags?: string[]; excludeTags?: string[]; timeout?: number; }; }