firecrawl-mcp 3.21.4 → 3.22.1

package/README.md

@@ -26,6 +26,24 @@ A Model Context Protocol (MCP) server that brings [Firecrawl](https://github.com
 
 ## Installation
 
+### Hosted MCP (keyless free tier)
+
+Connect to the remote hosted server with no setup:
+
+```
+https://mcp.firecrawl.dev/v2/mcp
+```
+
+On the keyless free tier, `scrape`, `search`, and `interact` work without an API key (rate-limited). Other tools such as `crawl`, `map`, `agent`, and `extract` still need a key.
+
+Prefer an API key or OAuth whenever the human can sign up. It unlocks the full tool set and higher limits. With a key, use:
+
+```
+https://mcp.firecrawl.dev/{FIRECRAWL_API_KEY}/v2/mcp
+```
+
+See the [MCP server docs](https://docs.firecrawl.dev/mcp-server) and the [agent onboarding guide](https://www.firecrawl.dev/agent-onboarding/SKILL.md) for setup details.
+
 ### Running with npx
 
 ```bash
@@ -195,37 +213,12 @@ Hosted Firecrawl can issue OAuth **access tokens** (`fco_…`) via the authoriza
 
 Use **access** tokens (`fco_…`) only. Refresh tokens (`fcr_…`) must be exchanged at the token endpoint, not passed to the scrape/search API.
 
-#### Optional Configuration
-
-##### Retry Configuration
-
-- `FIRECRAWL_RETRY_MAX_ATTEMPTS`: Maximum number of retry attempts (default: 3)
-- `FIRECRAWL_RETRY_INITIAL_DELAY`: Initial delay in milliseconds before first retry (default: 1000)
-- `FIRECRAWL_RETRY_MAX_DELAY`: Maximum delay in milliseconds between retries (default: 10000)
-- `FIRECRAWL_RETRY_BACKOFF_FACTOR`: Exponential backoff multiplier (default: 2)
-
-##### Credit Usage Monitoring
-
-- `FIRECRAWL_CREDIT_WARNING_THRESHOLD`: Credit usage warning threshold (default: 1000)
-- `FIRECRAWL_CREDIT_CRITICAL_THRESHOLD`: Credit usage critical threshold (default: 100)
-
 ### Configuration Examples
 
-For cloud API usage with custom retry and credit monitoring:
+For cloud API usage:
 
 ```bash
-# Required for cloud API
 export FIRECRAWL_API_KEY=your-api-key
-
-# Optional retry configuration
-export FIRECRAWL_RETRY_MAX_ATTEMPTS=5        # Increase max retry attempts
-export FIRECRAWL_RETRY_INITIAL_DELAY=2000    # Start with 2s delay
-export FIRECRAWL_RETRY_MAX_DELAY=30000       # Maximum 30s delay
-export FIRECRAWL_RETRY_BACKOFF_FACTOR=3      # More aggressive backoff
-
-# Optional credit monitoring
-export FIRECRAWL_CREDIT_WARNING_THRESHOLD=2000    # Warning at 2000 credits
-export FIRECRAWL_CREDIT_CRITICAL_THRESHOLD=500    # Critical at 500 credits
 ```
 
 For self-hosted instance:
@@ -236,10 +229,6 @@ export FIRECRAWL_API_URL=https://firecrawl.your-domain.com
 
 # Optional authentication for self-hosted
 export FIRECRAWL_API_KEY=your-api-key  # If your instance requires auth
-
-# Custom retry configuration
-export FIRECRAWL_RETRY_MAX_ATTEMPTS=10
-export FIRECRAWL_RETRY_INITIAL_DELAY=500     # Start with faster retries
 ```
 
 ### Usage with Claude Desktop
@@ -253,96 +242,43 @@ Add this to your `claude_desktop_config.json`:
       "command": "npx",
       "args": ["-y", "firecrawl-mcp"],
       "env": {
-        "FIRECRAWL_API_KEY": "YOUR_API_KEY_HERE",
-
-        "FIRECRAWL_RETRY_MAX_ATTEMPTS": "5",
-        "FIRECRAWL_RETRY_INITIAL_DELAY": "2000",
-        "FIRECRAWL_RETRY_MAX_DELAY": "30000",
-        "FIRECRAWL_RETRY_BACKOFF_FACTOR": "3",
-
-        "FIRECRAWL_CREDIT_WARNING_THRESHOLD": "2000",
-        "FIRECRAWL_CREDIT_CRITICAL_THRESHOLD": "500"
+        "FIRECRAWL_API_KEY": "YOUR_API_KEY_HERE"
       }
     }
   }
 }
 ```
 
-### System Configuration
-
-The server includes several configurable parameters that can be set via environment variables. Here are the default values if not configured:
-
-```typescript
-const CONFIG = {
-  retry: {
-    maxAttempts: 3, // Number of retry attempts for rate-limited requests
-    initialDelay: 1000, // Initial delay before first retry (in milliseconds)
-    maxDelay: 10000, // Maximum delay between retries (in milliseconds)
-    backoffFactor: 2, // Multiplier for exponential backoff
-  },
-  credit: {
-    warningThreshold: 1000, // Warn when credit usage reaches this level
-    criticalThreshold: 100, // Critical alert when credit usage reaches this level
-  },
-};
-```
-
-These configurations control:
-
-1. **Retry Behavior**
-
-   - Automatically retries failed requests due to rate limits
-   - Uses exponential backoff to avoid overwhelming the API
-   - Example: With default settings, retries will be attempted at:
-     - 1st retry: 1 second delay
-     - 2nd retry: 2 seconds delay
-     - 3rd retry: 4 seconds delay (capped at maxDelay)
-
-2. **Credit Usage Monitoring**
-   - Tracks API credit consumption for cloud API usage
-   - Provides warnings at specified thresholds
-   - Helps prevent unexpected service interruption
-   - Example: With default settings:
-     - Warning at 1000 credits remaining
-     - Critical alert at 100 credits remaining
-
-### Rate Limiting and Batch Processing
-
-The server utilizes Firecrawl's built-in rate limiting and batch processing capabilities:
-
-- Automatic rate limit handling with exponential backoff
-- Efficient parallel processing for batch operations
-- Smart request queuing and throttling
-- Automatic retries for transient errors
-
 ## How to Choose a Tool
 
 Use this guide to select the right tool for your task:
 
-- **If you know the exact URL(s) you want:**
-  - For one: use **scrape** (with JSON format for structured data)
-  - For many: use **batch_scrape**
+- **If you know the exact URL you want:** use **scrape** (with JSON format for structured data)
+- **If you have multiple known URLs:** call **scrape** for each URL. If you specifically need one bulk API operation, use the Firecrawl API batch endpoint outside MCP.
 - **If you need to discover URLs on a site:** use **map**
 - **If you want to search the web for info:** use **search**
 - **If you need complex research across multiple unknown sources:** use **agent**
 - **If you want to analyze a whole site or section:** use **crawl** (with limits!)
-- **If you need interactive browser automation** (click, type, navigate): use **scrape** + **interact**
+- **If you need interactive browser automation** (click, type, navigate): use **interact** with a URL for a fresh page, or **scrape** + **interact** when you already scraped the page or need tighter scrape control
 
 ### Quick Reference Table
 
 | Tool         | Best for                                       | Returns                        |
 | ------------ | ---------------------------------------------- | ------------------------------ |
 | scrape       | Single page content                            | JSON (preferred) or markdown   |
-| interact     | Interact with a scraped page                   | Execution result               |
-| batch_scrape | Multiple known URLs                            | JSON (preferred) or markdown[] |
+| interact     | Interact with a URL or scraped page            | Execution result + scrapeId for URL mode |
 | map          | Discovering URLs on a site                     | URL[]                          |
-| crawl        | Multi-page extraction (with limits)            | markdown/html[]                |
+| crawl        | Multi-page extraction (with limits)            | final crawl status/data after internal polling |
+| parse        | Files and hosted upload refs                   | markdown, JSON, or document output |
+| extract      | Structured extraction from URLs                | JSON structured data           |
 | search       | Web search for info                            | results[]                      |
 | agent        | Complex multi-source research                  | JSON (structured data)         |
+| monitor      | Recurring page checks                          | monitor/check metadata and diffs |
+| research     | Paper and GitHub repository research           | research results and repo matches |
 
 ### Format Selection Guide
 
-When using `scrape` or `batch_scrape`, choose the right format:
+When using `scrape`, choose the right format:
 
 - **JSON format (recommended for most cases):** Use when you need specific data from a page. Define a schema based on what you need to extract. This keeps responses small and avoids context window overflow.
 - **Markdown format (use sparingly):** Only when you genuinely need the full page content, such as reading an entire article for summarization or analyzing page structure.
@@ -359,12 +295,12 @@ Scrape content from a single URL with advanced options.
 
 **Not recommended for:**
 
-- Extracting content from multiple pages (use batch_scrape for known URLs, or map + batch_scrape to discover URLs first, or crawl for full page content)
+- Extracting content from multiple pages (use repeated scrape calls for known URLs, or map + scrape to discover URLs first, or crawl for full page content)
 - When you're unsure which page contains the information (use search)
 
 **Common mistakes:**
 
-- Using scrape for a list of URLs (use batch_scrape instead).
+- Passing a list of URLs to one scrape call. Call scrape once per URL in MCP. If you specifically need one bulk API operation, use the Firecrawl API batch endpoint outside MCP.
 - Using markdown format by default (use JSON format to extract only what you need).
 
 **Choosing the right format:**
@@ -434,72 +370,7 @@ Scrape content from a single URL with advanced options.
 
 - JSON structured data, markdown, branding profile, or other formats as specified.
 
-### 2. Batch Scrape Tool (`firecrawl_batch_scrape`)
-
-Scrape multiple URLs efficiently with built-in rate limiting and parallel processing.
-
-**Best for:**
-
-- Retrieving content from multiple pages, when you know exactly which pages to scrape.
-
-**Not recommended for:**
-
-- Discovering URLs (use map first if you don't know the URLs)
-- Scraping a single page (use scrape)
-
-**Common mistakes:**
-
-- Using batch_scrape with too many URLs at once (may hit rate limits or token overflow)
-
-**Prompt Example:**
-
-> "Get the content of these three blog posts: [url1, url2, url3]."
-
-**Usage Example:**
-
-```json
-{
-  "name": "firecrawl_batch_scrape",
-  "arguments": {
-    "urls": ["https://example1.com", "https://example2.com"],
-    "options": {
-      "formats": ["markdown"],
-      "onlyMainContent": true
-    }
-  }
-}
-```
-
-**Returns:**
-
-- Response includes operation ID for status checking:
-
-```json
-{
-  "content": [
-    {
-      "type": "text",
-      "text": "Batch operation queued with ID: batch_1. Use firecrawl_check_batch_status to check progress."
-    }
-  ],
-  "isError": false
-}
-```
-
-### 3. Check Batch Status (`firecrawl_check_batch_status`)
-
-Check the status of a batch operation.
-
-```json
-{
-  "name": "firecrawl_check_batch_status",
-  "arguments": {
-    "id": "batch_1"
-  }
-}
-```
-
-### 4. Map Tool (`firecrawl_map`)
+### 2. Map Tool (`firecrawl_map`)
 
 Map a website to discover all indexed URLs on the site.
 
@@ -510,7 +381,7 @@ Map a website to discover all indexed URLs on the site.
 
 **Not recommended for:**
 
-- When you already know which specific URL you need (use scrape or batch_scrape)
+- When you already know which specific URL you need (use scrape)
 - When you need the content of the pages (use scrape after mapping)
 
 **Common mistakes:**
@@ -536,7 +407,7 @@ Map a website to discover all indexed URLs on the site.
 
 - Array of URLs found on the site
 
-### 5. Search Tool (`firecrawl_search`)
+### 3. Search Tool (`firecrawl_search`)
 
 Search the web and optionally extract content from search results.
 
@@ -581,7 +452,7 @@ Search the web and optionally extract content from search results.
 
 > "Find the latest research papers on AI published in 2023."
 
-### 5b. Search Feedback Tool (`firecrawl_search_feedback`)
+### 3b. Search Feedback Tool (`firecrawl_search_feedback`)
 
 Sends structured feedback on a previous `firecrawl_search` result. The first feedback per search id refunds 1 credit and improves Firecrawl's search quality. Idempotent per search id.
 
@@ -623,7 +494,7 @@ Sends structured feedback on a previous `firecrawl_search` result. The first fee
 
 - `{ success, feedbackId, creditsRefunded, alreadySubmitted? }` JSON.
 
-### 5c. Generic Feedback Tool (`firecrawl_feedback`)
+### 3c. Generic Feedback Tool (`firecrawl_feedback`)
 
 Sends structured feedback for a completed v2 endpoint job through `/v2/feedback`.
 Use this for endpoint-level feedback on `scrape`, `parse`, `map`, or `search`
@@ -660,9 +531,9 @@ and small metadata objects. Do not include raw scrape/parse outputs.
 
 - `{ success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, alreadySubmitted?, warning? }` JSON.
 
-### 6. Crawl Tool (`firecrawl_crawl`)
+### 4. Crawl Tool (`firecrawl_crawl`)
 
-Starts an asynchronous crawl job on a website and extract content from all pages.
+Starts a crawl job, polls until it reaches a terminal state, and returns the final crawl status/data.
 
 **Best for:**
 
@@ -671,14 +542,14 @@ Starts an asynchronous crawl job on a website and extract content from all pages
 **Not recommended for:**
 
 - Extracting content from a single page (use scrape)
-- When token limits are a concern (use map + batch_scrape)
+- When token limits are a concern (use map + scrape for tighter control)
 - When you need fast results (crawling can be slow)
 
-**Warning:** Crawl responses can be very large and may exceed token limits. Limit the crawl depth and number of pages, or use map + batch_scrape for better control.
+**Warning:** Crawl responses can be very large and may exceed token limits. Limit the crawl depth and number of pages, or use map + scrape for tighter control.
 
 **Common mistakes:**
 
-- Setting limit or maxDepth too high (causes token overflow)
+- Setting limit or maxDiscoveryDepth too high (causes token overflow)
 - Using crawl for a single page (use scrape instead)
 
 **Prompt Example:**
@@ -692,7 +563,7 @@ Starts an asynchronous crawl job on a website and extract content from all pages
   "name": "firecrawl_crawl",
   "arguments": {
     "url": "https://example.com/blog/*",
-    "maxDepth": 2,
+    "maxDiscoveryDepth": 2,
     "limit": 100,
     "allowExternalLinks": false,
     "deduplicateSimilarURLs": true
@@ -700,25 +571,14 @@ Starts an asynchronous crawl job on a website and extract content from all pages
 }
 ```
 
-**Returns:**
 
-- Response includes operation ID for status checking:
+**Returns:**
 
-```json
-{
-  "content": [
-    {
-      "type": "text",
-      "text": "Started crawl for: https://example.com/* with job ID: 550e8400-e29b-41d4-a716-446655440000. Use firecrawl_check_crawl_status to check progress."
-    }
-  ],
-  "isError": false
-}
-```
+- Final crawl status and data after internal polling, including `id`, `status`, `completed`, `total`, `creditsUsed`, `expiresAt`, `next`, and `data`. Use the returned `id` with `firecrawl_check_crawl_status` if you need to re-check the job later.
 
-### 7. Check Crawl Status (`firecrawl_check_crawl_status`)
+### 5. Check Crawl Status (`firecrawl_check_crawl_status`)
 
-Check the status of a crawl job.
+Check the status and results of an existing crawl job by ID.
 
 ```json
 {
@@ -733,7 +593,33 @@ Check the status of a crawl job.
 
 - Response includes the status of the crawl job:
 
-### 8. Extract Tool (`firecrawl_extract`)
+### 6. Parse Tool (`firecrawl_parse`)
+
+Parse local files or hosted upload references with Firecrawl's `/v2/parse` endpoint.
+
+**Best for:** PDFs, Word documents, spreadsheets, HTML files, and other documents that need markdown or structured JSON output. Hosted MCP supports a two-step upload-ref flow; local direct file reads require a self-hosted `FIRECRAWL_API_URL`.
+
+**Not recommended for:** Remote URLs (use scrape), multiple files in one call (call parse once per file), or browser-only actions such as screenshots and clicks.
+
+**Hosted MCP flow:** Hosted MCP cannot read the caller's filesystem directly. Call `firecrawl_parse` with `filePath` to receive a short-lived upload command and `nextToolCall`, upload the file locally, then call `firecrawl_parse` again with the returned `uploadRef`. Minting the hosted upload URL requires Firecrawl auth or keyless eligibility. In local `npx firecrawl-mcp` mode, direct file parsing currently requires `FIRECRAWL_API_URL` pointing to a self-hosted Firecrawl API; a plain cloud API-key-only local server cannot read and upload files through this tool.
+
+**Usage Example:**
+
+```json
+{
+  "name": "firecrawl_parse",
+  "arguments": {
+    "filePath": "/absolute/path/to/document.pdf",
+    "formats": ["markdown"],
+    "parsers": ["pdf"],
+    "zeroDataRetention": true
+  }
+}
+```
+
+**Returns:** Parsed document content or hosted upload instructions with a `nextToolCall`.
+
+### 7. Extract Tool (`firecrawl_extract`)
 
 Extract structured information from web pages using LLM capabilities. Supports both cloud AI and self-hosted LLM extraction.
 
@@ -806,7 +692,7 @@ When using a self-hosted instance, the extraction will use your configured LLM.
 }
 ```
 
-### 9. Agent Tool (`firecrawl_agent`)
+### 8. Agent Tool (`firecrawl_agent`)
 
 Autonomous web research agent. This is a separate AI agent layer that independently browses the internet, searches for information, navigates through pages, and extracts structured data based on your query.
 
@@ -887,7 +773,7 @@ Then poll with `firecrawl_agent_status` using the returned job ID.
 
 - Job ID for status checking. Use `firecrawl_agent_status` to poll for results.
 
-### 10. Check Agent Status (`firecrawl_agent_status`)
+### 9. Check Agent Status (`firecrawl_agent_status`)
 
 Check the status of an agent job and retrieve results when complete. Use this to poll for results after starting an agent.
 
@@ -908,7 +794,60 @@ Check the status of an agent job and retrieve results when complete. Use this to
 - `completed`: Research finished - response includes the extracted data
 - `failed`: An error occurred
 
-### 11. Monitor Tools (`firecrawl_monitor_*`)
+### 10. Interact Tool (`firecrawl_interact`)
+
+Interact with a fresh URL or with a page that was already opened by `firecrawl_scrape`.
+
+**Best for:** Clicking, typing, navigating, and extracting state from dynamic pages without restoring the deprecated browser tools.
+
+**Usage options:**
+
+- Pass `url` to scrape and open a page for interaction in one MCP call.
+- Pass `scrapeId` to continue interacting with an existing scraped page.
+- Pass exactly one of `url` or `scrapeId`, plus either `prompt` or `code`.
+
+**Usage Example:**
+
+```json
+{
+  "name": "firecrawl_interact",
+  "arguments": {
+    "url": "https://example.com",
+    "prompt": "Click the pricing link and summarize the visible plans"
+  }
+}
+```
+
+**Returns:** Interaction result and, for URL mode, the derived `scrapeId` for follow-up or cleanup.
+
+### 11. Stop Interact Tool (`firecrawl_interact_stop`)
+
+Stop an interact session for a scraped page when you are done interacting.
+
+```json
+{
+  "name": "firecrawl_interact_stop",
+  "arguments": {
+    "scrapeId": "scrape-id-here"
+  }
+}
+```
+
+### 12. Research Tools (`firecrawl_research_*`)
+
+Search and inspect papers and GitHub repositories through the research MCP tools.
+
+**Available research tools:**
+
+- `firecrawl_research_search_papers`: search research papers.
+- `firecrawl_research_inspect_paper`: inspect one paper.
+- `firecrawl_research_related_papers`: find related papers.
+- `firecrawl_research_read_paper`: read paper content.
+- `firecrawl_research_search_github`: search GitHub repositories.
+
+**Best for:** Literature review, paper lookup, and repository discovery workflows where the agent needs a focused research surface instead of general web scraping.
+
+### 13. Monitor Tools (`firecrawl_monitor_*`)
 
 Create and manage recurring page monitors. Monitors run scheduled scrapes or crawls, diff each result against the last retained snapshot, and can notify by webhook or email.
 
@@ -973,6 +912,7 @@ Pass `body` when you need crawl targets, JSON change tracking, custom retention,
 - `firecrawl_monitor_get`: get one monitor.
 - `firecrawl_monitor_update`: update fields including `goal`, `judgeEnabled`, `webhook`, and `notification`.
 - `firecrawl_monitor_run`: trigger a check now.
+- `firecrawl_monitor_delete`: delete a monitor (destructive; only call when the user intends to remove it).
 - `firecrawl_monitor_checks`: list checks, optionally filtered by status.
 - `firecrawl_monitor_check`: get page-level results, including `diff`, `snapshot`, `judgment.meaningful`, and `judgment.meaningfulChanges`.
 
@@ -982,7 +922,6 @@ The server includes comprehensive logging:
 
 - Operation status and progress
 - Performance metrics
-- Credit usage monitoring
 - Rate limit tracking
 - Error conditions
 
@@ -991,19 +930,15 @@ Example log messages:
 ```
 [INFO] Firecrawl MCP Server initialized successfully
 [INFO] Starting scrape for URL: https://example.com
-[INFO] Batch operation queued with ID: batch_1
-[WARNING] Credit usage has reached warning threshold
-[ERROR] Rate limit exceeded, retrying in 2s...
+[ERROR] Rate limit exceeded
 ```
 
 ## Error Handling
 
 The server provides robust error handling:
 
-- Automatic retries for transient errors
-- Rate limit handling with backoff
+- API rate-limit errors surfaced to the MCP client
 - Detailed error messages
-- Credit usage warnings
 - Network resilience
 
 Example error response:
@@ -1013,7 +948,7 @@ Example error response:
   "content": [
     {
       "type": "text",
-      "text": "Error: Rate limit exceeded. Retrying in 2 seconds..."
+      "text": "Error: Rate limit exceeded"
     }
   ],
   "isError": true

package/dist/index.js

@@ -1385,9 +1385,11 @@ function buildMonitorCreateBody(args2) {
     args2.page,
     args2.pages
   );
-  if (urls.length === 0) {
+  const queries = Array.isArray(args2.queries) ? args2.queries.filter((q) => typeof q === "string").map((q) => q.trim()).filter(Boolean) : [];
+  const isSearch = queries.length > 0;
+  if (urls.length === 0 && !isSearch) {
     throw new Error(
-      "firecrawl_monitor_create requires either `body`, `page`, or `pages`."
+      "firecrawl_monitor_create requires either `body`, `page`/`pages`, or `queries`."
     );
   }
   const goal = typeof args2.goal === "string" ? args2.goal.trim() : "";
@@ -1396,6 +1398,25 @@ function buildMonitorCreateBody(args2) {
       "firecrawl_monitor_create shorthand requires `goal`. Use `body` for advanced requests without a goal."
     );
   }
+  let target;
+  if (isSearch) {
+    const includeDomains = Array.isArray(args2.includeDomains) ? args2.includeDomains.filter(
+      (d) => typeof d === "string"
+    ) : void 0;
+    const excludeDomains = Array.isArray(args2.excludeDomains) ? args2.excludeDomains.filter(
+      (d) => typeof d === "string"
+    ) : void 0;
+    target = {
+      type: "search",
+      queries,
+      ...typeof args2.searchWindow === "string" && args2.searchWindow.trim() ? { searchWindow: args2.searchWindow.trim() } : {},
+      ...typeof args2.maxResults === "number" ? { maxResults: args2.maxResults } : {},
+      ...includeDomains && includeDomains.length > 0 ? { includeDomains } : {},
+      ...excludeDomains && excludeDomains.length > 0 ? { excludeDomains } : {}
+    };
+  } else {
+    target = { type: "scrape", urls };
+  }
   const webhookUrl = typeof args2.webhookUrl === "string" ? args2.webhookUrl.trim() : "";
   const email = typeof args2.email === "string" && args2.email.trim() ? {
     email: {
@@ -1405,13 +1426,13 @@ function buildMonitorCreateBody(args2) {
     }
   } : void 0;
   return {
-    name: typeof args2.name === "string" && args2.name.trim() ? args2.name.trim() : `Monitor ${urls[0]}`,
+    name: typeof args2.name === "string" && args2.name.trim() ? args2.name.trim() : isSearch ? `Monitor ${queries[0]}` : `Monitor ${urls[0]}`,
     schedule: {
       text: typeof args2.scheduleText === "string" && args2.scheduleText.trim() ? args2.scheduleText.trim() : "every 30 minutes",
       timezone: typeof args2.timezone === "string" && args2.timezone.trim() ? args2.timezone.trim() : "UTC"
     },
     goal,
-    targets: [{ type: "scrape", urls }],
+    targets: [target],
     ...email ? { notification: email } : {},
     ...webhookUrl ? {
       webhook: {
@@ -1434,20 +1455,38 @@ function registerMonitorTools(server2) {
       // Additive; creates a new monitor without deleting existing monitors or external content.
     },
     description: `
-Create a Firecrawl monitor \u2014 a recurring scrape or crawl that diffs each result against the last retained snapshot.
+Create a Firecrawl monitor \u2014 a recurring scrape, crawl, or search that diffs each result against the last retained snapshot.
 
-Prefer the simple path: pass \`page\` or \`pages\` plus \`goal\`. The tool will create a scrape monitor with a 30-minute schedule and meaningful-change judging enabled by the API. Use \`body\` only for advanced requests such as crawl targets, JSON change tracking, custom retention, or manual \`judgeEnabled\` control.
+Prefer the simple path: pass \`page\` or \`pages\` plus \`goal\` to monitor specific URLs, OR pass \`queries\` plus \`goal\` to monitor web search results for new/changed hits. The tool will create the monitor with a 30-minute schedule and meaningful-change judging enabled by the API. Use \`body\` only for advanced requests such as crawl targets, JSON change tracking, custom retention, or manual \`judgeEnabled\` control.
 
 Meaningful-change judge: set \`goal\` to a plain-language description of what the user actually cares about. \`judgeEnabled\` defaults to true when \`goal\` is set, so providing \`goal\` is enough. Page webhooks expose \`isMeaningful\` and \`judgment\` on \`monitor.page\` events.
 
 Simple fields:
 - \`page\`: one page URL to monitor.
 - \`pages\`: multiple page URLs to monitor.
-- \`goal\`: plain-English instruction for what changes matter. Required for the simple path.
+- \`queries\`: one or more search queries (1-12) to monitor instead of fixed URLs. Each check runs the searches and diffs the result set, so you get alerted when new or changed results appear. Mutually exclusive with \`page\`/\`pages\` in the simple path.
+- \`searchWindow\`: optional recency window for search targets \u2014 one of \`5m\`, \`15m\`, \`1h\`, \`6h\`, \`24h\`, \`7d\` (default \`24h\`).
+- \`maxResults\`: optional max results per search, 1-50 (default 10).
+- \`includeDomains\` / \`excludeDomains\`: optional domain allow/deny lists for search targets.
+- \`goal\`: plain-English instruction for what changes matter. Required for the simple path (and always required when \`queries\` are set \u2014 web monitors must have a goal).
 - \`scheduleText\`: optional natural-language schedule, default \`every 30 minutes\`.
 - \`email\`: optional email recipient for summaries.
 - \`webhookUrl\`: optional webhook URL. Configures \`monitor.page\` and \`monitor.check.completed\`.
 
+**Search-mode example:**
+
+\`\`\`json
+{
+  "name": "firecrawl_monitor_create",
+  "arguments": {
+    "queries": ["new LLM release", "frontier model launch"],
+    "goal": "Notify me about major new LLM model releases.",
+    "searchWindow": "24h",
+    "maxResults": 10
+  }
+}
+\`\`\`
+
 Goal guidance:
 - Expand the user's one-line monitoring intent into a concise 2-3 sentence monitor goal.
 - State what should trigger an alert, restate any scope the user gave, and include intent-specific exclusions only when obvious from the user's request.
@@ -1456,7 +1495,7 @@ Goal guidance:
 - If the user says they do not care about something, include that explicitly. It is okay to ask whether they want to ignore specific noise when it is likely to matter.
 - Do not invent page-specific sections, thresholds, entities, or business rules unless the user mentioned them.
 
-Full \`body\` requests require: \`name\`, \`schedule\` (with \`cron\` or \`text\`), and \`targets\` (one or more \`{ type: 'scrape', urls: [...] }\` or \`{ type: 'crawl', url: '...' }\`). Optional: \`goal\`, \`judgeEnabled\`, \`webhook\`, \`notification\`, \`retentionDays\`.
+Full \`body\` requests require: \`name\`, \`schedule\` (with \`cron\` or \`text\`), and \`targets\` (one or more \`{ type: 'scrape', urls: [...] }\`, \`{ type: 'crawl', url: '...' }\`, or \`{ type: 'search', queries: [...], searchWindow?, maxResults?, includeDomains?, excludeDomains? }\`). Optional: \`goal\` (required when any search target is present), \`judgeEnabled\`, \`webhook\`, \`notification\`, \`retentionDays\`.
 
 **Markdown-mode (default):** Each check produces a unified text diff of the page's markdown. No extra configuration needed.
 
@@ -1532,6 +1571,11 @@ Full \`body\` requests require: \`name\`, \`schedule\` (with \`cron\` or \`text\
       body: z2.record(z2.string(), z2.any()).optional(),
       page: z2.string().optional(),
       pages: z2.array(z2.string()).optional(),
+      queries: z2.array(z2.string()).optional(),
+      searchWindow: z2.enum(["5m", "15m", "1h", "6h", "24h", "7d"]).optional(),
+      maxResults: z2.number().int().min(1).max(50).optional(),
+      includeDomains: z2.array(z2.string()).optional(),
+      excludeDomains: z2.array(z2.string()).optional(),
       goal: z2.string().optional(),
       name: z2.string().optional(),
       scheduleText: z2.string().optional(),
@@ -3484,20 +3528,20 @@ Do not store multi-MB outputs in feedback. Use concise notes, issue codes, URLs,
 server.addTool({
   name: "firecrawl_crawl",
   annotations: {
-    title: "Start a site crawl",
+    title: "Run a site crawl",
     readOnlyHint: false,
-    // Starts an asynchronous crawl job, creating a persistent server-side job.
+    // Starts a server-side crawl job and polls until the job reaches a terminal state.
     openWorldHint: true,
     // Crawls user-specified URLs across the public web.
     destructiveHint: false
     // Reads pages from target sites; does not delete or alter external websites.
   },
   description: `
- Starts a crawl job on a website and extracts content from all pages.
+ Starts a crawl job on a website, polls until it reaches a terminal state, and returns the final crawl status/data.
  
  **Best for:** Extracting content from multiple related pages, when you need comprehensive coverage.
- **Not recommended for:** Extracting content from a single page (use scrape); when token limits are a concern (use map + batch_scrape); when you need fast results (crawling can be slow).
- **Warning:** Crawl responses can be very large and may exceed token limits. Limit the crawl depth and number of pages, or use map + batch_scrape for better control.
+ **Not recommended for:** Extracting content from a single page (use scrape); when token limits are a concern (use map + scrape for tighter control); when you need fast results (crawling can be slow).
+ **Warning:** Crawl responses can be very large and may exceed token limits. Limit the crawl depth and number of pages, or use map + scrape for tighter control.
  **Common mistakes:** Setting limit or maxDiscoveryDepth too high (causes token overflow) or too low (causes missing pages); using crawl for a single page (use scrape instead). Using a /* wildcard is not recommended.
  **Prompt Example:** "Get all blog posts from the first two levels of example.com/blog."
  **Usage Example:**
@@ -3514,7 +3558,7 @@ server.addTool({
    }
  }
  \`\`\`
- **Returns:** Operation ID for status checking; use firecrawl_check_crawl_status to check progress.
+ **Returns:** Final crawl status and data after internal polling, including the crawl id. Use firecrawl_check_crawl_status only when you need to re-check an existing crawl ID later.
  ${SAFE_MODE ? "**Safe Mode:** Read-only crawling. Webhooks and interactive actions are disabled for security." : ""}
  `,
   parameters: z4.object({
@@ -3846,24 +3890,28 @@ server.addTool({
     // Transient page interactions only; does not delete monitors, jobs, or external sites.
   },
   description: `
-Interact with a previously scraped page in a live browser session. Scrape a page first with firecrawl_scrape, then use the returned scrapeId to click buttons, fill forms, extract dynamic content, or navigate deeper.
+Interact with a page in a live browser session: click buttons, fill forms, extract dynamic content, or navigate deeper.
 
 **Best for:** Multi-step workflows on a single page \u2014 searching a site, clicking through results, filling forms, extracting data that requires interaction.
-**Requires:** A scrapeId from a previous firecrawl_scrape call (found in the metadata of the scrape response).
+**Two ways to target a page:**
+- Pass a \`url\` to interact directly. The session is opened for you in one call (use this for a fresh page).
+- Pass a \`scrapeId\` from a previous firecrawl_scrape to reuse that already-loaded page (cheaper when you just scraped it).
 
 **Arguments:**
-- scrapeId: The scrape job ID from a previous scrape (required)
+- url: Page to interact with; opens a session for you (use this OR scrapeId)
+- scrapeId: Scrape job ID from a previous scrape, found in its metadata (use this OR url)
 - prompt: Natural language instruction describing the action to take (use this OR code)
 - code: Code to execute in the browser session (use this OR prompt)
 - language: "bash", "python", or "node" (optional, defaults to "node", only used with code)
-- timeout: Execution timeout in seconds, 1-300 (optional, defaults to 30)
+- timeout: Interact execution timeout in seconds, 1-300 (optional, defaults to 30)
+- scrapeOptions: Optional scrape controls used only with url mode, such as waitFor, maxAge, proxy, or zeroDataRetention
 
-**Usage Example (prompt):**
+**Usage Example (prompt, direct via url):**
 \`\`\`json
 {
   "name": "firecrawl_interact",
   "arguments": {
-    "scrapeId": "scrape-id-from-previous-scrape",
+    "url": "https://example.com/products",
     "prompt": "Click on the first product and tell me its price"
   }
 }
@@ -3883,24 +3931,71 @@ Interact with a previously scraped page in a live browser session. Scrape a page
 **Returns:** Execution result including output, stdout, stderr, exit code, and live view URLs.
 `,
   parameters: z4.object({
-    scrapeId: z4.string(),
-    prompt: z4.string().optional(),
-    code: z4.string().optional(),
+    scrapeId: z4.string().trim().min(1).optional(),
+    url: z4.string().trim().url().optional(),
+    prompt: z4.string().trim().min(1).optional(),
+    code: z4.string().trim().min(1).optional(),
     language: z4.enum(["bash", "python", "node"]).optional(),
-    timeout: z4.number().min(1).max(300).optional()
+    timeout: z4.number().min(1).max(300).optional(),
+    scrapeOptions: scrapeParamsSchema.omit({ url: true }).partial().optional()
+  }).refine((data) => Boolean(data.scrapeId) !== Boolean(data.url), {
+    message: "Provide either 'url' (interact directly) or 'scrapeId' (reuse a previous scrape), not both."
+  }).refine((data) => !data.scrapeOptions || Boolean(data.url), {
+    message: "scrapeOptions can only be used with 'url' mode."
   }).refine((data) => data.code || data.prompt, {
     message: "Either 'code' or 'prompt' must be provided."
   }),
   execute: async (args2, { session, log }) => {
     const client = getClient(session);
-    const { scrapeId, prompt, code, language, timeout } = args2;
-    log.info("Interacting with scraped page", { scrapeId });
+    const {
+      scrapeId: providedScrapeId,
+      url,
+      prompt,
+      code,
+      language,
+      timeout,
+      scrapeOptions
+    } = args2;
+    let scrapeId = providedScrapeId;
+    const openedFromUrl = !scrapeId;
+    if (openedFromUrl) {
+      log.info("Opening interact session from url", { url });
+      const cleanedScrapeOptions = removeEmptyTopLevel(scrapeOptions ?? {});
+      const scraped = await client.scrape(String(url), {
+        ...cleanedScrapeOptions,
+        origin: ORIGIN
+      });
+      scrapeId = scraped?.metadata?.scrapeId;
+      if (!scrapeId) {
+        return asText2({
+          error: "Could not open an interact session: the scrape did not return a scrapeId. Try firecrawl_scrape first, then pass its scrapeId.",
+          url
+        });
+      }
+    }
+    if (!scrapeId) {
+      return asText2({
+        error: "Could not open an interact session: missing scrapeId.",
+        url
+      });
+    }
+    const activeScrapeId = scrapeId;
+    log.info("Interacting with page", { scrapeId: activeScrapeId });
     const interactArgs = { origin: ORIGIN };
     if (prompt) interactArgs.prompt = prompt;
     if (code) interactArgs.code = code;
     if (language) interactArgs.language = language;
     if (timeout != null) interactArgs.timeout = timeout;
-    const res = await client.interact(scrapeId, interactArgs);
+    const res = await client.interact(activeScrapeId, interactArgs);
+    if (openedFromUrl && res && typeof res === "object" && !Array.isArray(res)) {
+      return asText2({
+        ...res,
+        scrapeId: activeScrapeId
+      });
+    }
+    if (openedFromUrl) {
+      return asText2({ scrapeId: activeScrapeId, result: res });
+    }
     return asText2(res);
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl-mcp",
-  "version": "3.21.4",
+  "version": "3.22.1",
   "description": "MCP server for Firecrawl — search, scrape, and interact with the web. Supports both cloud and self-hosted instances. Features include web search, scraping, page interaction, batch processing, and LLM-powered content analysis.",
   "type": "module",
   "mcpName": "io.github.firecrawl/firecrawl-mcp-server",