Firecrawl MCP Server

Instructions

Implementation Reference

• src/index.ts:1123-1169 (handler)

  The main handler logic for the 'firecrawl_search' tool. Validates arguments using isSearchOptions, performs the search via client.search, handles errors and credits, and formats the results into a readable text output with URLs, titles, descriptions, and 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), '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:408-480 (schema)

  The Tool definition including name, description, and detailed inputSchema for validating 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:863-873 (registration)

  Registration of the firecrawl_search tool (as SEARCH_TOOL) in the list of available tools returned by ListToolsRequestSchema handler.
  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 helper function used in the handler 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' ); }
• src/index.ts:561-577 (helper)

  TypeScript interface defining the expected shape of arguments for firecrawl_search tool, used by the type guard.
  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; }; }