---
canonical_url: "https://docs.composio.dev/toolkits/simplescraper_mcp"
markdown_url: "https://docs.composio.dev/toolkits/simplescraper_mcp.md"
product: "platform"
version: null
last_updated: null
---

# Simplescraper MCP

Simplescraper MCP lets agents create scraping recipes and extract structured live web data through an authenticated remote MCP server.

- **Category:** model context protocol
- **Auth:** DCR_OAUTH
- **Composio-managed OAuth available?** No
- **Tools:** 13
- **Triggers:** 0
- **Slug:** `SIMPLESCRAPER_MCP`
- **Version:** 20260924_00

## Tools

### Create recipe

**Slug:** `SIMPLESCRAPER_MCP_CREATE_RECIPE`

Create a new scrape recipe with a name, URL, and selectors.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | URL of the page to be scraped |
| `name` | string | Yes | Name of the recipe to create |
| `selectors` | array | Yes | Array of selectors defining what data to extract (max 100) |

### Extract markdown

**Slug:** `SIMPLESCRAPER_MCP_EXTRACT_MARKDOWN`

Fetch one page and return its body as clean Markdown. Renders JavaScript before extraction. Returns markdown plus metadata (title, word count).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | Full URL of the page to extract, including protocol (e.g. 'https://example.com/blog/post') |

### Extract urls

**Slug:** `SIMPLESCRAPER_MCP_EXTRACT_URLS`

Discover all page URLs on a website by parsing its sitemap (and the sitemap index if present). Returns a deduplicated list of page URLs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `domain` | string | Yes | Full URL of the site including protocol, e.g. 'https://example.com' |
| `url_limit` | number | No | Maximum number of URLs to return (default: no limit; sites can have tens of thousands of URLs) |
| `sitemap_limit` | number | No | For sites whose top-level sitemap is an INDEX of nested sitemaps, limits how many nested sitemaps to traverse. Useful for very large sites where you want a fast partial sample. |

### Get latest results

**Slug:** `SIMPLESCRAPER_MCP_GET_LATEST_RESULTS`

Get the most recent scraped results for a recipe. Returns the existing data from the last completed run without scraping again.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | number | No | Maximum number of results to return |
| `offset` | number | No | Number of results to skip for pagination |
| `orderBy` | string ("index" | "timestamp") | No | Field to order/sort results by ('index' is default. 'timestamp' orders by most recently SCRAPED results) |
| `recipe_id` | string | Yes | ID of the recipe to get latest results for |

### Get recipe

**Slug:** `SIMPLESCRAPER_MCP_GET_RECIPE`

Retrieve full details of a specific scrape recipe: name, URL, creation date, last run time, and selectors.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `recipe_id` | string | Yes | ID of the recipe to retrieve |

### Get results

**Slug:** `SIMPLESCRAPER_MCP_GET_RESULTS`

Fetch the scraped data from a specific run by results_id. Supports ordering (by index or timestamp) and pagination via limit and offset.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | number | No | Maximum number of scrape results to return |
| `offset` | number | No | Number of results to skip for pagination |
| `orderBy` | string ("index" | "timestamp") | No | Field to order/sort results by ('index' is default. 'timestamp' orders by most recently SCRAPED results) |
| `results_id` | string | Yes | ID of the results to retrieve |

### Get results history

**Slug:** `SIMPLESCRAPER_MCP_GET_RESULTS_HISTORY`

List previous scrape runs for a recipe. Each entry has results_id, scrape timestamp, and page count. Returns run metadata only, not the scraped data itself.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | number | No | Maximum number of history items to return (default: 100) |
| `offset` | number | No | Number of history items to skip for pagination (default: 0) |
| `recipe_id` | string | Yes | ID of the recipe to get results history for |

### List recipes

**Slug:** `SIMPLESCRAPER_MCP_LIST_RECIPES`

List the user's scrape recipes, with optional filters by domain, name keyword, or recent activity, and sorting by creation date, last-run, or name.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host` | string | No | Filter recipes by specific website or host (e.g., 'amazon.com') - use EXACT domain name only |
| `limit` | number | No | Maximum number of recipes to return (default: 50) |
| `order` | string ("asc" | "desc") | No | sort order (ascending or descending, default: desc) |
| `query` | string | No | Query string to filter recipes by name (requires exact match, not fuzzy search) |
| `offset` | number | No | Number of recipes to skip for pagination (default: 0) |
| `has_run` | boolean | No | If true, include only recipes that have been run before |
| `orderBy` | string ("date_created" | "date_last_ran_timestamp" | "name") | No | Field to order/sort results by ('date_last_ran_timestamp' for most recently run recipes) |

### Run recipe

**Slug:** `SIMPLESCRAPER_MCP_RUN_RECIPE`

Run a scrape recipe to extract fresh data from its configured URL. Supports async mode, source URL override, markdown extraction, and batch (crawler) mode.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `urls` | array | No | Optional array of URLs to scrape through this recipe in one run. Replaces the recipe's saved crawler list, forces crawler+async mode, and returns a results_id immediately (use get_results to fetch). Up to 5000 URLs; the number scraped is capped by your credits. |
| `recipe_id` | string | Yes | ID of the recipe to run |
| `run_async` | boolean | No | If true, returns a result ID immediately and runs the scrape asynchronously (default: false) |
| `source_url` | string | No | Optional URL to run the recipe on (overrides the recipe's default URL - must be encoded) |
| `use_crawler` | boolean | No | If true, scrapes URLs added to the crawler instead of the source URL (default: false) |
| `extract_markdown` | boolean | No | If true, extracts a markdown version of the page in addition to structured data (default: false) |

### Screenshot

**Slug:** `SIMPLESCRAPER_MCP_SCREENSHOT`

Capture a screenshot of a web page (1 credit per request). Returns JSON with a hosted screenshot URL by default. Supports full-page capture, custom viewport, format/quality, delays, and popup/ad hiding. Defaults output to 'url' so the response stays small; 'binary' returns raw image bytes and is not suited to an MCP text response.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | The URL of the page to capture, including protocol (e.g. 'https://example.com') |
| `delay` | number | No | Seconds to wait after page load before capturing, 0-15 (default: 0) |
| `store` | boolean | No | If true, saves the screenshot to cloud storage (automatically true when output is 'url') |
| `format` | string ("png" | "jpeg" | "webp") | No | Image format (default: 'png') |
| `output` | string ("base64" | "url" | "binary") | No | How to return the image: 'url' (default here - a hosted screenshot URL with a 30-day TTL), 'base64' (image embedded in the JSON), or 'binary' (raw bytes; not recommended for MCP) |
| `quality` | number | No | Compression quality 1-100 for JPEG/WebP (default: 80; ignored for PNG) |
| `hide_ads` | boolean | No | If true, suppresses ad network content (default: true) |
| `full_page` | boolean | No | If true, captures the full scrollable page rather than just the viewport (default: false) |
| `wait_until` | string ("load" | "domcontentloaded" | "networkidle0" | "networkidle2") | No | Navigation completion condition (default: 'load') |
| `hide_popups` | boolean | No | If true, suppresses cookie consent banners and popups (default: true) |
| `viewport_width` | number | No | Browser viewport width in pixels, 320-3840 (default: 1920) |
| `hide_background` | boolean | No | If true, captures a transparent background (PNG/WebP only, default: false) |
| `viewport_height` | number | No | Browser viewport height in pixels, 320-3840 (default: 1080) |
| `wait_for_selector` | string | No | CSS selector to wait for before capturing |
| `device_scale_factor` | string ("1" | "1.5" | "2" | "3") | No | Device pixel ratio for the capture: '1', '1.5', '2', or '3' (default: '1') |

### Smart extract

**Slug:** `SIMPLESCRAPER_MCP_SMART_EXTRACT`

Extract specific named fields from one page using AI. Pass a comma-separated schema like 'product name, price, sku' and get those fields back as a structured object, plus the CSS selectors that matched them.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | The URL of the page to be scraped |
| `schema` | string | Yes | A comma-separated list of properties to extract (e.g., 'product name, price, description') |
| `recipe_id` | string | No | Optional ID of a recipe to use its cookies and settings |

### Update batch urls

**Slug:** `SIMPLESCRAPER_MCP_UPDATE_BATCH_URLS`

Add or replace the list of batch (crawler) URLs for a recipe. 'append' adds to the existing list, 'replace' overwrites it.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `recipe_id` | string | Yes | ID of the recipe to update batch URLs for |
| `batch_mode` | string ("append" | "replace") | No | Operation mode: 'append' (default) adds to existing URLs, 'replace' overwrites them |
| `batch_urls` | array | Yes | Array of URLs to process in the batch operation |

### Update recipe

**Slug:** `SIMPLESCRAPER_MCP_UPDATE_RECIPE`

Update an existing scrape recipe's name, URL, or selectors. Supports 'replace' (default) or 'merge' modes for selector updates.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | No | New URL for the recipe |
| `name` | string | No | New name for the recipe |
| `recipe_id` | string | Yes | ID of the recipe to update |
| `selectors` | array | No | Array of selectors to update |
| `update_mode` | string ("replace" | "merge") | No | Mode for updating selectors: 'replace' (default) or 'merge' |