# API Reference — MCP Scraper

Source: https://mcpscraper.dev/docs

# API & SDK Reference

One generated contract exposes all 252 MCP tools through four SDK packages, the CLI, direct cURL, and the hosted REST API. Use the same scraper, browser, workflow, billing, and memory capabilities from the language or shell your application already uses.

View SDK on GitHub ↗ Browse the 252-tool surface Connected account quickstart

Before the first connection

## Know the monthly fee and the usage meter.

A paid plan supplies the shared Credit balance. Each active Nango-backed provider account is a separate $3/month add-on, and connected work draws from that balance as it runs.

1. Choose a paid plan
   Starter, Growth, and Scale include Credits, but no active provider connections.
2. Approve the connection fee
   Each active Nango connection adds $3/month. The Integrations screen shows this before OAuth begins.
3. Use the shared Credits
   Connected work costs 2 Credits per function run, 2 per proxy request, and 5 per compute-second measured from milliseconds.
4. Review and remove
   Use the dashboard Credits tab for the current balance and rates, History for settled usage, and Integrations to disconnect accounts you no longer need.

For a scheduled connection job, add the 75-Credit base for each started run. Agent mode also adds 1.5× the model provider's reported cost. [See the billing example and full rate card.](/pricing#connected-billing)

## Authentication

Pass your key in the `x-api-key` header. Query-string API keys are rejected so keys do not end up in URLs, browser history, or logs.

```
x-api-key: sk_live_••••
```

Connected account → RAG

## Store one exact approved read as a searchable snapshot

`import_service_connection_to_memory` composes a tenant-owned connection read with a Memory write. The server rechecks the exact live `readTools` grant, redacts the result, marks it as untrusted provider data, writes it at a stable server-generated path, and indexes it in the same request.

### Import one Google Drive read

```
mcpscraper tools call import_service_connection_to_memory \
  --args '{"connectionId":"conn_…","providerConfigKey":"google-drive","tool":"<exact readTools entry>","args":{},"vault":"Library","title":"Drive snapshot"}' \
  --json
```

### Discover before calling

```
mcpscraper tools call list_service_connections --args '{}' --json
mcpscraper tools call describe_service_connection_tool \
  --args '{"connectionId":"conn_…","tool":"<readTools entry>"}' \
  --json
```

### Required authority

Supply the exact `connectionId`, matching `providerConfigKey`, one current read tool, and an existing ordinary notes-vault handle. `args` and `title` are optional.

### Stable and inspectable

The caller cannot choose the path. The same connection, tool, and canonical arguments upsert the same Markdown snapshot. The receipt includes path, hash, source bytes, indexed chunks, and search status.

### Bounded by design

Arguments are capped at 64 KiB and the serialized result at 1 MB. Binary, base64, oversized, inactive, unapproved, action, admin, channel-vault, and secure-vault requests fail closed.

This is one snapshot from one approved read. It does not paginate, hydrate a corpus, import an entire account, run continuously, propagate deletions, or build normalized tables. A successful response reports `search_ready`; if storage succeeds without indexed chunks, it explicitly reports `stored_not_indexed`. Use `export_connected_service_data` only for its supported Gmail, Google Calendar, Google Search Console, Zoom, Slack, Resend, and Meta datasets.

Connected accounts

## Export a supported time range in one call

Use `export_connected_service_data` for its dedicated Gmail, Google Calendar, Google Search Console, Zoom, Slack, Resend, or Meta adapters. It is separate from the one-read Memory snapshot tool. For these supported datasets, the server owns pagination and delivery; large results become private JSONL instead of overflowing the agent context.

### Complete Slack channel with threads

```
mcpscraper tools call export_connected_service_data \
  --args '{"connectionId":"conn_…","dataset":"slack_channel_messages","channelId":"C1234567890","allTime":true,"includeThreads":true,"delivery":"artifact"}' \
  --json
```

Slack export includes top-level messages, threaded replies, reactions, and file metadata. It never joins a channel or downloads private file binaries. If the result is partial, pass its complete `continuation` object back unchanged.

### Last seven days of email

```
mcpscraper tools call export_connected_service_data \
  --args '{"connectionId":"conn_…","dataset":"emails","lastDays":7}' \
  --json
```

### Renew an expired download link

```
mcpscraper tools call renew_connected_data_download \
  --args '{"artifactId":"artifact_…"}' \
  --json
```

### Resend operating history

```
mcpscraper tools call export_connected_service_data \
  --args '{"connectionId":"conn_…","dataset":"resend_data","lastDays":7,"maxItems":2000}' \
  --json
```

### Search Console performance

```
mcpscraper tools call export_connected_service_data \
  --args '{"connectionId":"conn_…","dataset":"search_console_performance","lastDays":28,"maxItems":5000}' \
  --json
```

### Inspect multiple Search Console URLs

```
mcpscraper tools call read_service_connection \
  --args '{"connectionId":"conn_…","tool":"inspect-urls","args":{"siteUrl":"sc-domain:example.com","urls":["https://example.com/","https://example.com/pricing"]}}' \
  --json
```

### Filtered scheduled Search Console data

```
mcpscraper tools call export_search_console_table_data \
  --args '{"tableName":"gsc_performance_…","filters":[{"column":"date","op":"gte","value":"2026-07-01"},{"column":"query","op":"like","value":"roof repair"}],"sort":[{"column":"clicks","direction":"desc"}],"maxRows":10000}' \
  --json
```

Small live exports return inline. Large exports are private, retained for seven days, and use 15-minute signed URLs. Each live invocation returns at most 5,000 records. Search Console's `search_console_performance` dataset walks every accessible property for a fresh requested range. For recurring history, create a scheduled action in `connection_sync` mode; after its first successful run, read the connection's `tableName`, use `table-describe` and `table-query` for exact filtering, then use `export_search_console_table_data` to download up to 50,000 matching stored rows. Search Console returns provider-selected top rows and is not guaranteed exhaustive. Resend's aggregate `resend_data` mode walks 12 collections; six core resources can also be selected individually, and each provider page hydrates at most 25 records. A partial live export returns a continuation object that preserves the original range.

Search Console also exposes API-only batches without creating a table: `inspect-urls` and `query-search-analytics-batch` are reads; `add-sites-batch`, `submit-sitemaps-batch`, `delete-sites-batch`, and `delete-sitemaps-batch` are gated actions. They return per-item receipts and can be granted to scheduled agent runs. Delete batches plan by default and require the exact confirmation token from `describe_service_connection_tool` before execution.

Official remote MCP · OAuth

## Connect Resend without adding 85 global tools

The dashboard opens Resend's hosted OAuth flow at `mcp.resend.com/mcp`. After consent, MCP Scraper discovers the official account-scoped tools and exposes only the reviewed intersection through its generic connection bridge and each schedule's exact grant.

85 official tools discovered

33 approved reads

45 gated actions

7 admin tools blocked

### Available to reads

Sent and received email, attachments, logs, contacts, broadcasts, templates, automations, domains, segments, topics, webhooks, and other account metadata.

### Available only behind action gates

Drafting, sending, scheduling, updating, verification, removal, event triggers, and audience changes require both the account action switch and the exact tool grant.

### Never delegated

API-key and OAuth-grant administration, the raw editor connector, and raw webhook creation remain outside MCP and Mastra execution. Credential-bearing fields are redacted from approved outputs.

Resend tools are connection-scoped capabilities, not 85 new globally callable names in the base MCP catalog. Inspect the current connection first, then grant an exact read or action. Policy source: [official Resend MCP repository ↗](https://github.com/resend/resend-mcp). OAuth and API-key fallback behavior: [official MCP documentation ↗](https://resend.com/docs/mcp-server).

Unified tool contract

## All 252 tools, on every supported surface

The catalog contains 151 scraper, connection, and automation tools plus 101 memory tools. Every surface is generated from the same checked-in manifest, so a missing or renamed tool fails the SDK parity check before release.

252 MCP tools

4 SDK packages

30 typed namespaces

| Surface | Install | 252-tool access | Reference |
|---|---|---|---|
| **Node.js — scraper** | `npm install mcpscraper-sdk` | `ScraperClient.tools` | [npm package ↗](https://www.npmjs.com/package/mcpscraper-sdk) |
| **Node.js — memory** | `npm install mcpscraper-memory-sdk` | `McpToolsClient` | [npm package ↗](https://www.npmjs.com/package/mcpscraper-memory-sdk) |
| **Python — scraper** | `pip install "mcpscraper-sdk @ git+https://github.com/VilovietaSEO/mcpscraper-sdk.git#subdirectory=packages/scraper-python"` | `ScraperClient.tools` | [source package ↗](https://github.com/VilovietaSEO/mcpscraper-sdk/tree/main/packages/scraper-python) |
| **Python — memory** | `pip install "mcpscraper-memory-sdk @ git+https://github.com/VilovietaSEO/mcpscraper-sdk.git#subdirectory=packages/memory-python"` | `McpToolsClient` | [source package ↗](https://github.com/VilovietaSEO/mcpscraper-sdk/tree/main/packages/memory-python) |
| **CLI** | `npm install -g mcpscraper-cli` | `tools list · describe · call` | [npm package ↗](https://www.npmjs.com/package/mcpscraper-cli) |
| **cURL** | `curl + jq` | `JSON-RPC tools/list + tools/call` | [252-tool catalog ↗](https://github.com/VilovietaSEO/mcpscraper-sdk/blob/main/docs/curl-tools.md) |

### CLI discovery and invocation

```
export MCPSCRAPER_API_KEY=sk_live_your_key
mcpscraper tools list
mcpscraper tools describe import_service_connection_to_memory
mcpscraper tools call credits_info --args '{}' --json
```

### Direct JSON-RPC with cURL

```
curl --retry 3 --retry-all-errors --retry-delay 1 \
  -X POST https://mcpscraper.dev/mcp \
  -H "x-api-key: $MCPSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

Canonical source: [mcp.tools.json ↗](https://github.com/VilovietaSEO/mcpscraper-sdk/blob/main/contracts/mcp.tools.json). The SDK repository also contains generated types, package-specific examples, parity validators, and the complete cURL catalog.

## Endpoint map

Use the smallest surface that matches the job. SERP harvest is for Google results; website endpoints fetch public URLs; YouTube endpoints go directly to YouTube search, channels, and transcripts.

| Method | Path | Use | Limit |
|---|---|---|---|
| POST | /mcp | Unified MCP JSON-RPC transport for all 249 scraper, browser, workflow, connection, billing, and memory tools | x-api-key; tools/list + tools/call |
| POST | /harvest/sync | Google SERP harvest: PAA, AI Overview, local pack, forums, videos, perspectives, entity IDs | 110–285s by maxQuestions, max 200 |
| POST | /harvest | Async SERP harvest with job polling and optional webhook callback | Callback must be HTTPS public URL |
| GET | /jobs, /jobs/:id | List or fetch saved SERP harvest jobs for the authenticated user | User-scoped |
| POST | /extract-url | Single public URL extraction: title, meta, headings, markdown body, and JSON-LD schema | Public http/https hosts only |
| POST | /map-urls | BFS internal URL discovery for a public website | maxUrls up to 10,000 |
| POST | /extract-site | Map then scrape per-page content for a site; with audit params returns the full technical SEO audit | maxPages up to 10,000; rotateProxies for blocked sites |
| GET | /extract-site/status/:id | Poll status + artifacts for a bulk async crawl/audit job | User-scoped |
| POST | /screenshot | Full-page screenshot of a public URL (desktop or mobile viewport) | Public http/https hosts only |
| POST | /serp-intelligence/capture | Structured SERP Intelligence snapshot for a query (product capture path) | 4 Credits headless or 14 headful; optional snapshots add 1 per attempted URL |
| POST | /serp-intelligence/page-snapshots | Capture optional public ranking-page evidence for one or more URLs/targets | 1 Credit per attempted URL; requested capacity held, unused capacity refunded; no private/localhost/internal URLs |
| POST | /youtube/harvest | YouTube search or channel harvest with video metadata and thumbnails | maxVideos 1-500 API, dashboard slider 10-200 |
| POST | /youtube/transcribe | Transcript by video ID with text, timestamp chunks, Markdown, and HTML | Depends on caption/Whisper availability |
| POST | /facebook/search | Discover advertisers by name or keyword in the Facebook Ad Library | maxResults 1-20 |
| POST | /facebook/page-intel | Scan all ads for an advertiser — copy, headline, CTA, status, creative type | Accepts libraryId, pageId, or query |
| POST | /facebook/ad | Extract full metadata for a single ad by library ID | Returns video, image, and text fields |
| POST | /facebook/video-transcribe | Transcribe an organic Facebook reel, video, watch, or share URL | quality best, hd, or sd; renders page first |
| POST | /facebook/transcribe | Transcribe audio from a direct Facebook ad video CDN URL returned by /facebook/page-intel | Use the videoUrl from page-intel, not a public post URL |
| POST | /facebook/media | Download video or image from fbcdn.net CDN URLs | fbcdn.net and cdninstagram.com only |
| POST | /maps/search | Google Maps business search — up to 50 profile candidates for a category + location | maxResults 1-50 |
| POST | /maps/place | One Google Maps business profile with optional reviews | includeReviews + maxReviews; reviews billed per card |
| POST | /directory/run | Build a directory dataset: select US city markets by population, run Maps search per city in parallel, return CSV | minPopulation, maxCities, concurrency |
| POST | /instagram/profile-content | Discover public Instagram post, reel, and tv links from a profile | maxItems + maxScrolls; public content only |
| POST | /instagram/media-download | Download text, images, reel audio/video, and optional transcript for one post | public / login-gated limits apply |
| POST | /reddit/thread | Capture a Reddit post and its full comment tree (author, score, depth, body) from any reddit.com thread URL | maxComments optional; handles Reddit bot wall via residential proxy |
| POST | /video/analyze | Start an async frame-by-frame + transcript video breakdown; $1 per 120 frames requested (max 480), videos up to 30 minutes | Direct .mp4/.webm/.mov URLs; returns runId |
| POST | /video/status | Poll a video breakdown run; returns progress, then the full report; reconciles billing down if fewer frames were usable | Free to call |
| GET | /workflows/definitions | List runnable workflows for agent packets, market audits, Maps/SERP comparison, PAA briefs, and AI Overview language guidance | User-scoped |
| POST | /workflows/run | Run a hosted workflow and return summary plus artifacts | workflowId + input; respects concurrency limit |
| GET | /workflows/runs/:id | Fetch workflow status and artifact list | User-scoped |
| GET | /workflows/runs/:id/artifacts/:artifactId | Download workflow artifacts such as evidence JSON, CSVs, Markdown briefs, and reports | Artifact must belong to caller |
| POST | /agent/sessions | Open an interactive browser session (stealth + CAPTCHA solving). Returns a session id and watch link | Needs ≥1 credit balance |
| POST | /agent/sessions/:id/screenshot | See the page: screenshot image plus DOM elements with click coordinates and text | Billed per minute of use |
| POST | /agent/sessions/:id/{goto,click,type,scroll,press,read} | Drive the browser — navigate, click, type, scroll, press keys, read the page | 120 credits / minute of use |
| POST | /agent/sessions/:id/replay/{start,stop} | Record an MP4 replay of the session for later review | Multiple per session |
| DELETE | /agent/sessions/:id | Close the browser session and stop the meter | Session-scoped |
| GET | /me | Account info: plan, credit balance, concurrency limit | API key auth |
| GET | /billing/balance | Current credit balance in millicredits | API key auth |
| GET | /billing/credits | Full per-tool cost catalog (live credit prices for every tool) | API key auth |
| GET | /rates | Public pricing contract, including the $3/month active-connection add-on and connected function, proxy, and compute rates | 2 Credits per function run, 2 per provider proxy request, and 5 per compute-second, prorated from milliseconds |
| GET | /ledger | Recent credit ledger entries (debits, refunds, top-ups) | User-scoped |
| POST | /api-key/rotate | Rotate your API key | Invalidates the previous key |
| POST | /memory/mcp-call | Generic compatibility gateway to all 101 memory tools — persistent per-user notes, facts, vaults, scheduled actions, tables, and channels | {toolName, args}; 10 MB free / 5 GB Pro storage |
| GET | /memory/connect | Get a ready-to-paste MCP connector config (URL + key) for Claude/Cursor/Windsurf/Codex/ChatGPT | Auto-provisions your memory key on first call |

## Limits and safety

- API keys must be sent in the x-api-key header. Query-string keys are rejected.
- /harvest/sync blocks 110–285s scaled by maxQuestions (serpOnly→110s, ≤50→170s, ≤100→230s, 101–200→up to 285s), under the 300s ceiling; maxQuestions is capped at 200.
- /extract-site handles up to 10,000 pages; /map-urls up to 10,000 URLs.
- URL tools only fetch public http/https hosts. Localhost, private IPs, and internal network addresses are blocked.
- Webhook callbacks must be HTTPS public URLs.

## Errors

| HTTP | Meaning | What to do |
|---|---|---|
| 400 | Bad input | Missing field, invalid URL, private URL target, or invalid mode. |
| 401 | Auth | Missing or invalid x-api-key header. |
| 402 | Payment | The requested operation needs available credits. |
| 429 | Limit | User already has an active harvest running. |
| 500/503 | Upstream | Google, YouTube, browser, or transcription provider blocked or timed out. Retry with a cleaner query or lower max value. |