Firecrawl MCP Server

Instructions

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "latest AI research papers 2023",
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true
    }
  }
}

Implementation Reference

• src/index.ts:1151-1193 (handler)

  The handler function for the 'firecrawl_search' tool. Validates input with isSearchOptions, performs the search using the Firecrawl client, formats the results including URLs, titles, descriptions, and optional markdown content, and handles errors.

        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:408-502 (schema)

  The Tool definition for 'firecrawl_search' including name, detailed description, and comprehensive inputSchema specifying 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.
  
  **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:955-966 (registration)

  Registration of all tools including SEARCH_TOOL in the listTools request 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:814-821 (helper)

  Type guard helper function to validate 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'
    );
  }