Firecrawl MCP Server

Instructions

Implementation Reference

• src/index.ts:1158-1200 (handler)

  Handler for the firecrawl_search tool. Validates input using isSearchOptions, calls Firecrawl client's search method with retry logic, formats search results into a readable text output, and returns the content or error.
  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'}` ); } // 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:415-509 (schema)

  Tool definition object including name, detailed description, and comprehensive input schema for parameters like query, limit, lang, country, scrapeOptions, etc.
  const SEARCH_TOOL: Tool = { name: 'firecrawl_search', description: ` Search the web and optionally extract content from search results. This is the most powerful search tool available, and if available you should always default to using this tool for any web search needs. **Best for:** Finding specific information across multiple websites, when you don't know which website has the information; when you need the most relevant content for a query. **Not recommended for:** When you already know which website to scrape (use scrape); when you need comprehensive coverage of a single website (use map or crawl). **Common mistakes:** Using crawl or map for open-ended questions (use search instead). **Prompt Example:** "Find the latest research papers on AI published in 2023." **Usage Example:** \`\`\`json { "name": "firecrawl_search", "arguments": { "query": "latest AI research papers 2023", "limit": 5, "lang": "en", "country": "us", "scrapeOptions": { "formats": ["markdown"], "onlyMainContent": true } } } \`\`\` **Returns:** Array of search results (with optional scraped content). `, 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:962-974 (registration)

  Registers the firecrawl_search tool (as SEARCH_TOOL) in the list of available tools returned by the ListTools handler.
  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ SCRAPE_TOOL, MAP_TOOL, CRAWL_TOOL, CHECK_CRAWL_STATUS_TOOL, SEARCH_TOOL, EXTRACT_TOOL, DEEP_RESEARCH_TOOL, GENERATE_LLMSTXT_TOOL, ], }));
• src/index.ts:821-828 (helper)

  Type guard function used to validate input arguments for 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:731-750 (helper)

  TypeScript interface defining the shape of SearchOptions used for input validation in 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; includeTags?: string[]; excludeTags?: string[]; timeout?: number; }; }