SocialScrape

By SocialScrape 👁 4 views ▲ 0 votes

SocialScrape is a social media scraping API for developers. One API key covers 29 platforms, including TikTok, Instagram, YouTube, Facebook, LinkedIn, X and Reddit, and posts come back in the same shape from each one, so you write one parser. Failed requests and cached repeats are free. There are no scrapers to run and nothing to patch when a platform changes.

pip install 'socialscrape-mcp[http]'`,

{ "mcpServers": { "socialscrape": {
    "url": "https://api.socialscrape.dev/mcp",
    "headers": { "x-api-key": "ss_live_..." } } } }

# socialscrape-mcp

The SocialScrape MCP server: social media data (profiles, posts, comments, search, ads,
transcripts) for Claude, ChatGPT, Cursor and any other MCP client. SocialScrape hosts this server at `https://api.socialscrape.dev/mcp`; this package is the same server to run on your own machine.

It is **generated from SocialScrape's endpoint registry** and grouped so an agent sees a usable number of tools instead of one per endpoint:

| Tools | What |
|---|---|
| `get_transcript`, `search`, `get_profile`, `get_post`, `get_comments` | The jobs agents do most, across platforms. The platform is an argument. |
| one per platform (`github`, `facebook`, `twitter`, ...) | `resource` picks the data (`user`, `profile.posts`, ...); parameters follow. |
| `describe` | Exact parameters, allowed values, price, example arguments. Free, no API call. |
| `call_endpoint`, `batch`, `get_job`, `monitors`, `get_credits` | Any endpoint by id, up to 100 requests in one call, async jobs, webhooks, balance. |

Only built endpoints appear as tools. A platform shows up in the next release after its endpoints are built.

Every result starts with `ok | credits charged: 1 | credits remaining: 4999` (and the structured
copy carries the numbers as fields). Failures are free and come back as `isError` with the API's
error code, a `retryable` flag and what to do next.

## Use it

**Hosted (the main way).** SocialScrape runs this server at `https://api.socialscrape.dev/mcp` (streamable HTTP). There are two ways to sign in.

1. Sign in, with no key to copy. Add the URL as a connector, then sign in with your SocialScrape account and approve the connection.
   - Claude: Settings, Connectors, Add custom connector, paste the URL.
   - ChatGPT: add a connector with the URL and choose OAuth.
   - Cursor: add a server with the URL and sign in when asked.
   - Claude Code: `claude mcp add --transport http socialscrape https://api.socialscrape.dev/mcp`, then `/mcp` to sign in.
2. An API key in a header, `x-api-key: ss_live_...`.
   - Claude Code: `claude mcp add --transport http socialscrape https://api.socialscrape.dev/mcp --header "x-api-key: ss_live_..."`
   - Cursor, in `~/.cursor/mcp.json`:

```json
{ "mcpServers": { "socialscrape": {
    "url": "https://api.socialscrape.dev/mcp",
    "headers": { "x-api-key": "ss_live_..." } } } }
```

Each signed-in connection shows in the dashboard as a key named "MCP connector". Calls are charged to the team like any key, and revoking that key disconnects that connector. The tools are the same as this package's. Add `?platforms=github,threads` or `?toolsets=core` to the URL to narrow the list.

**Local (this package).** For offline clients, or if you want the server on your own machine, your MCP client starts it as a subprocess over stdio:

```json
{ "mcpServers": { "socialscrape": {
    "command": "uvx", "args": ["socialscrape-mcp"],
    "env": { "SOCIALSCRAPE_API_KEY": "ss_live_..." } } } }
```

Get a key at <https://socialscrape.dev/sign-up?utm_source=github&utm_medium=repo&utm_campaign=socialscrape-mcp>. Tool discovery works without a key; a tool call without one
explains how to add it.

**Fewer tools.** Some clients cap the number of tools (Cursor warns past 40). Narrow the list in the `env`
block:

| | Setting |
|---|---|
| only some platforms | `SOCIALSCRAPE_PLATFORMS=github,threads` |
| only the cross-platform and account tools | `SOCIALSCRAPE_TOOLSETS=core` |
| only the platform tools | `SOCIALSCRAPE_TOOLSETS=platforms` |

With `core` alone an agent still reaches every endpoint through `describe` and `call_endpoint`.

**Serve it over HTTP yourself.** To run your own copy of the hosted server on a host you control, install the extra: `pip install 'socialscrape-mcp[http]'`, then `socialscrape-mcp http --host
127.0.0.1 --port 8080`. Each request carries its own key in the `x-api-key` header (or
`Authorization: Bearer ...`), and `?platforms=` and `?toolsets=` narrow the tools. This copy is yours to run and
secure.

## Settings (environment)

| Variable | Default | |
|---|---|---|
| `SOCIALSCRAPE_API_KEY` | none | stdio only; the HTTP mode reads each request's key |
| `SOCIALSCRAPE_API_URL` | `https://api.socialscrape.dev` | |
| `SOCIALSCRAPE_MCP_TRIM` | `1` | ask for `trim=true` (no null fields, no `extra`) unless a call says otherwise; saves context |
| `SOCIALSCRAPE_MCP_MAX_CHARS` | `100000` | longest answer; longer lists are cut to whole items, transcripts come in windows (`offset`) |
| `SOCIALSCRAPE_MCP_TIMEOUT` | `70` | seconds to wait for the API |
| `SOCIALSCRAPE_MCP_ALLOWED_ORIGINS` | any | HTTP mode only; comma list, set it to refuse browser calls from other origins |
| `SOCIALSCRAPE_PLATFORMS`, `SOCIALSCRAPE_TOOLSETS` | all | see above |

<!-- mcp-name: dev.socialscrape/socialscrape -->