Model Context Protocol

# Use the scrapers from your AI client

Three tools exposed over MCP, so Claude, Cursor or any other client can pull TikTok creator emails, YouTube channel contacts and video transcripts without you writing a line of scraping code.
[Connect it](#setup) [See the tools](#tools)

## The tools

| Tool | What it returns | Cost |
| --- | --- | --- |
| find_tiktok_creators | One row per creator: handle, bio, followers, likes, and any email, Instagram, YouTube or WhatsApp link they publish | ~$1 / 1,000 profiles |
| find_youtube_channel_emails | Channel contact emails plus videos and Shorts with views, likes, tags and exact publish dates | ~$1.50 / 1,000 videos |
| get_video_transcripts | Transcripts for TikTok, Instagram Reels, YouTube and X, with optional timestamped segments | ~$2 / 1,000 transcripts |

Every tool is backed by the same Apify actor as the standalone products, so the data is identical — the difference is that your assistant can call it directly.

## Connect it

The endpoint is a standard Streamable HTTP MCP server:

```
https://scrapelads.com/mcp
```

Add it to your client's MCP configuration. **Claude Desktop** (`claude_desktop_config.json`) and **Cursor** (`.cursor/mcp.json`) both use this shape:

```
{
  "mcpServers": {
    "scrapelads": {
      "url": "https://scrapelads.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_APIFY_TOKEN"
      }
    }
  }
}
```

Restart the client and the three tools appear. Any other MCP client that supports remote HTTP servers works the same way — point it at the URL and send the header.

## Authentication

You bring your own Apify token. It is read from the `Authorization` header, passed straight through to the actor API and never stored on our side.

1. **Create a token.** In the Apify Console, open _Settings → Integrations_ and create an API token.
2. **Add it to the header.**`Authorization: Bearer <token>` in your client config.
3. **Run a tool.** Usage is billed to that Apify account at the per-result prices above, against whatever plan or free credit it has.

**No token, no cost.** Calls without a token come back with a short message telling the model to ask you for one — they never fall back to our account.

## Let your coding agent set it up

Using **Claude Code** or **Codex**? Paste this prompt into it and the agent adds the server, asks for your token and checks the connection.

```
Set up the ScrapeLads MCP server for me.

Server details:
- Name: scrapelads
- Transport: Streamable HTTP (remote server, nothing to install)
- URL: https://scrapelads.com/mcp
- Auth: header "Authorization: Bearer <APIFY_TOKEN>", where APIFY_TOKEN is my Apify API token (Apify Console → Settings → Integrations)

Steps:
1. Work out whether you are Claude Code or Codex, and use that tool's own MCP config:
   - Claude Code: run
     claude mcp add --transport http --scope user scrapelads https://scrapelads.com/mcp --header "Authorization: Bearer $APIFY_TOKEN"
   - Codex: add this to ~/.codex/config.toml
     [mcp_servers.scrapelads]
     url = "https://scrapelads.com/mcp"
     bearer_token_env_var = "APIFY_TOKEN"
     and make sure APIFY_TOKEN is set in my shell environment.
2. If APIFY_TOKEN is not already set, ask me for the token. Never commit it to a repository or print it back in full.
3. Verify the server: POST {"jsonrpc":"2.0","id":1,"method":"tools/list"} to https://scrapelads.com/mcp and confirm three tools come back: find_tiktok_creators, find_youtube_channel_emails and get_video_transcripts.
4. Tell me if I need to restart the session for the tools to appear. Then offer one small test call (maxResults 3), and only run it after I say yes, because tool calls are billed to my Apify account.
```

## What a conversation looks like

Once connected, you stop describing the task and start asking for the result:

- "Find 50 skincare creators with more than 20k followers that publish an email, and give me the list."
- "Which of these YouTube channels have a contact email, and what did they post last week?"
- "Transcribe these five TikToks and summarise what each one is selling."

The assistant calls the tool, receives JSON, and works with it directly — no copy-paste between a scraper UI and the chat.

## Protocol details

The server implements the MCP Streamable HTTP transport over JSON-RPC 2.0, supporting `initialize`, `ping`, `tools/list` and `tools/call`. It is stateless: no session id is issued, and every `POST` is independent, so it works behind any proxy or serverless host. CORS is open, so browser-based clients can call it too.

The full source — about 300 lines with no dependencies — is public at [github.com/charbeld/scrapelads-mcp](https://github.com/charbeld/scrapelads-mcp), along with the security notes and a CI job that verifies the live endpoint on every push.

## Questions

**Do I need an Apify account?**

Yes. The MCP server is a thin layer over three Apify actors, and the token you supply determines who pays. The free Apify tier includes monthly usage credit, enough to try all three tools.

**How is this different from the standalone actors?**

The data and pricing are the same. The difference is the interface: the actors are called from the Apify Console or their REST API, while this lets an AI assistant call them mid-conversation.

**Is my token stored anywhere?**

No. It is read from the request header, used for that single upstream call, and discarded. Nothing is logged or persisted.

**What happens if a run takes a long time?**

The tools use Apify's synchronous endpoint, which waits up to 300 seconds. Keep `maxResults` small — a few dozen rows — to stay well inside that. For large jobs, call the actor directly and poll for results.

**Can I use it from a script instead of an AI client?**

Yes. It is plain JSON-RPC over HTTPS: `POST` a `tools/call` message to `/mcp` with your token in the header and you get JSON back.

## Connect in about two minutes

Create an Apify token, paste the config, restart your client. The tools are listed the moment the connection opens.
[Get an Apify token](https://console.apify.com/settings/integrations)