socialcrawl-mcp

Give your AI agent access to 48 platforms and 381 endpoints — social media, commerce & product reviews, retail, app stores, places & travel, business reputation, news & finance, web research, full web scraping & browser automation, prediction markets, search trends, cross-platform Prism composites, and a universal meta-search — through a single API, with exact credit pricing for every endpoint

Overview | Installation | Setup | Usage | Tools | Platforms

Overview

socialcrawl-mcp is an MCP (Model Context Protocol) server that connects AI agents to the SocialCrawl API — a unified data API covering 48 platforms and 381 endpoints.

Retrieve profiles, posts, comments, search results, trending content, and analytics from TikTok, Instagram, YouTube, Twitter/X, LinkedIn, Reddit, GitHub, Hacker News, Polymarket, and 30 more platforms. Pull products, reviews, and sellers from Amazon, Walmart, Target, Home Depot, eBay, and Google Shopping; apps, charts, and reviews from Google Play and the Apple App Store; places, hotels, and traveler reviews from Tripadvisor and Google Business; brand reputation from Trustpilot; Korean search and Data Lab trend series from Naver; cross-web brand mentions with sentiment via Content Analysis; Google News headlines, Google Finance quotes, and Google Trends interest curves — plus web research via Tavily and Perplexity, AI-powered X search via Grok, and a single /search/everywhere endpoint that fans out across 14 sources in one call.

New in this release (v1.9.0): a dedicated socialcrawl_pricing tool that answers "what will this cost me" for every endpoint before a single credit is spent — the tier ladder, every flat override, all 26 metered endpoints with their real min–max band and exact charging rule, per-platform cost tables, and budget-filtered rankings. Five new retail and discovery platforms (Walmart, Target, Home Depot, eBay, plus four free API self-discovery endpoints), Naver Data Lab search-trend and shopping-insight series, a metered multi-country news search lane, and Reddit post detail, Threads post comments, TikTok on-screen text, and the Facebook full reels feed. Alongside the Prism family — server-side composite endpoints that fan out across many platforms and fold the results into one report. One API key, one consistent response format, every platform.

What the MCP server does:

• Discovers platforms and endpoints dynamically, or by free-text search across all 381 of them

• Fetches live data on your behalf across every platform, method, and composite

• Prices every call up front — ladder, flat, or metered band — so an agent can budget before it spends

• Validates requests locally before calling the API: required params, oneOf groups, enum values, integer ranges, parameter couplings, and CSV limits. A bad call fails free instead of burning credits

• Provides built-in API documentation the agent can query on demand, paged rather than truncated

Related MCP server: BulkPublish

Installation

Remote server (hosted — no install)

Connect straight to the hosted Streamable HTTP endpoint — nothing to install or run:

Claude Code (works in the CLI and Claude Code on the web / cloud sandboxes)

claude mcp add --scope user --transport http socialcrawl https://mcp.socialcrawl.dev/mcp \
  --header "Authorization: Bearer sc_your_key_here"

Any client that reads .mcp.json

{
  "mcpServers": {
    "socialcrawl": {
      "type": "http",
      "url": "https://mcp.socialcrawl.dev/mcp",
      "headers": { "Authorization": "Bearer ${SOCIALCRAWL_API_KEY}" }
    }
  }
}

Cursor / Windsurf / VS Code — choose the HTTP ("streamable-http") server type with the same URL and header. x-api-key: sc_your_key_here works as an alternative header.

The discovery tools (socialcrawl_list_platforms, socialcrawl_list_endpoints, socialcrawl_get_docs) work without a key, so you can explore before signing up. claude.ai custom connectors (Settings → Connectors) require OAuth, which ships in a follow-up release — use the header-based setup above in the meantime.

Prefer running it locally? Every stdio option below works exactly as before.

npm

npm install -g socialcrawl-mcp

Available on npm. Most users don't need this — the MCP client configs below use npx and auto-install on first run.

Claude Code (quickest)

claude mcp add --scope user socialcrawl -- npx -y socialcrawl-mcp

Then set your API key:

claude mcp add-env socialcrawl SOCIALCRAWL_API_KEY sc_your_key_here

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "socialcrawl": {
      "command": "npx",
      "args": ["-y", "socialcrawl-mcp"],
      "env": {
        "SOCIALCRAWL_API_KEY": "sc_your_key_here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "socialcrawl": {
      "command": "npx",
      "args": ["-y", "socialcrawl-mcp"],
      "env": {
        "SOCIALCRAWL_API_KEY": "sc_your_key_here"
      }
    }
  }
}

VS Code (Claude Code)

Add to .vscode/mcp.json in your project or your user settings:

{
  "servers": {
    "socialcrawl": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "socialcrawl-mcp"],
      "env": {
        "SOCIALCRAWL_API_KEY": "sc_your_key_here"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "socialcrawl": {
      "command": "npx",
      "args": ["-y", "socialcrawl-mcp"],
      "env": {
        "SOCIALCRAWL_API_KEY": "sc_your_key_here"
      }
    }
  }
}

Other MCP-compatible clients

Any MCP client that supports stdio transport can use this server. The general pattern is:

• Command: npx

• Args: ["-y", "socialcrawl-mcp"]

• Environment: SOCIALCRAWL_API_KEY set to your API key

Restart your AI client after saving the configuration.

Setup

1. Get your API key

Sign up at socialcrawl.dev and grab your API key from the dashboard. Every account starts with 100 free credits — no credit card required.

2. Add the key to your config

Replace sc_your_key_here in the installation config above with your actual API key (starts with sc_).

Usage

Ask your AI agent in natural language. The MCP server handles the rest.

Fetch a profile

Get the TikTok profile for @charlidamelio

The agent calls socialcrawl_request with platform: "tiktok", resource: "profile", params: { handle: "charlidamelio" } and returns structured profile data including followers, bio, verification status, and engagement metrics.

Search across platforms

Search YouTube for "machine learning tutorials"

Get post comments

Get the comments on this Instagram post: https://instagram.com/p/CwA1234abcd

Cross-platform research

Compare the follower counts of @mkbhd on TikTok, Instagram, YouTube, and Twitter

The agent makes 4 sequential API calls — one per platform — and compiles the results into a comparison.

Shop across retailers

Find the cheapest 65-inch OLED TV across Amazon, Walmart, Target, and eBay

Explore available endpoints

What social media platforms can you access?

Show me all the TikTok endpoints

Which endpoints can give me video transcripts?

The last one is a cross-platform socialcrawl_list_endpoints search — no platform needed, it looks across all 381 endpoints.

Learn the API from the API

How do I get started with SocialCrawl?

Show me exactly how to call the Prism comments endpoint

Is this MCP server's endpoint list up to date?

All three hit socialcrawl_discover and cost nothing.

Check what something costs before running it

What would it cost to run a Prism brand-mentions report?

Show me everything I can call for 1 credit

Why did that last call charge me 7 credits instead of 2?

The first two hit socialcrawl_pricing; the third reads the credit ledger via socialcrawl_check_balance with view: "transactions" and shows the deduction and refund rows for that request_id.

Access documentation

How does the SocialCrawl credit system work?

How do I page through a list endpoint?

Example response

Every response follows a unified envelope format:

{
  "success": true,
  "platform": "tiktok",
  "endpoint": "/v1/tiktok/profile",
  "data": {
    "content": { "text": "...", "media_urls": ["..."] },
    "author": { "username": "charlidamelio", "followers": 156000000 },
    "engagement": { "likes": 5200, "engagement_rate": 0.045 },
    "metadata": { "language": "en", "content_category": "entertainment" }
  },
  "credits_used": 1,
  "credits_remaining": 99
}

Available Tools

The MCP server exposes 9 tools:

Four of the nine tools work without an API key — they query local bundled data generated from the backend registry. socialcrawl_request, socialcrawl_check_balance, socialcrawl_monitors, and socialcrawl_web require a key. socialcrawl_discover uses a key when it has one and falls back to bundled data when it does not.

Discovery — the API describing itself, for free

socialcrawl_discover drives the /v1/utility/* family: four endpoints that let any client learn the whole API from inside the API, at 0 credits. They are served in-process from the endpoint registry — no upstream call, no network hop — so they can never drift from what is actually callable.

Why freshness matters. This server ships a catalogue generated when it was built; the API keeps moving. Data calls always hit the live API and keep working — but discovery, pricing, and local validation answer from that snapshot, so a newly added endpoint looks unknown until you upgrade. One free call tells you which situation you are in:

socialcrawl_discover  action: "freshness"

Bundled vs live. list_platforms, list_endpoints, pricing, and get_docs answer instantly from bundled data and need no key — prefer them for browsing. Reach for socialcrawl_discover when correctness matters more than latency: an endpoint looks missing, you need a metered endpoint's exact live price, or you are generating code that must match production today. Without a key it still answers everything except llms from bundled data, so discovery never hard-requires auth.

These same endpoints are plain HTTP, so a third-party integration or a non-MCP agent framework gets the identical information with a curl.

Pricing — know the cost before you spend

socialcrawl_pricing exists because a single number is a lie for most of the surface. SocialCrawl bills three ways:

• Ladder (294 endpoints) — the tier rate per request: standard 1cr, advanced 5cr, premium 10cr.

• Flat (61 endpoints, 18 of them free) — a per-endpoint override, e.g. /v1/search/everywhere at 20cr flat.

• Metered (26 endpoints) — the charge depends on the request. An upfront ceiling is deducted and refunded down to the work actually done.

Quoting a metered endpoint's base cost understates every call: /v1/search/news has a 1cr base but really charges 2–14cr depending on how many country legs return articles. The tool returns the real band, the registry's own charging rule, the parameters that move the bill, and the worst case to budget for:

action: "overview"   → ladder, every free endpoint, every flat override, every metered band + rule, cache TTLs, full refund matrix
action: "endpoint"   → one endpoint's price, rule, price-driving params, paging cost, worst case
action: "platform"   → a whole platform's cost table
action: "list"       → rank/filter by cost — "everything I can call for 1 credit", "the 10 most expensive endpoints"

It also states the rules that make the real charge differ from the sticker price: cache hits, idempotent replays, empty results, and upstream failures are all 0 credits.

Monitors — schedule any recipe

socialcrawl_monitors wraps any registry endpoint or Prism composite in a scheduled, stateful monitor (/v1/monitors/*). It re-runs the recipe hourly/daily/weekly (or on a cron), delivers each result to an HMAC-signed webhook, raises alerts on metric thresholds or changes, and keeps a per-run time-series you can read back. "Prism answers once; monitors watch it for you." Managing monitors costs 0 credits; each scheduled run bills the recipe's normal cost plus a 1-credit scheduling premium. See socialcrawl_get_docs topic monitors for the full contract.

Web — scrape, crawl, browse

socialcrawl_web drives the full web-scraping and browser-automation surface (the web platform, /v1/web/*) through a single action parameter:

• Sync reads — scrape (URL → markdown/HTML/screenshot/links), search (web search with page content), map (discover a site's URLs), extract (LLM structured data from a page).

• Async jobs — crawl a whole site, batch_scrape many URLs, or agent (autonomous multi-step web task); each returns a job you poll with job_get/job_list, inspect with job_errors (per-page failures), and stop with job_cancel. crawl_preview dry-runs a crawl's parameters for free before you pay for it.

• Monitors — monitor_create/list/get/update/delete/checks re-check a URL on a cadence and deliver changes to a webhook.

• Sessions — session_create/get/list, session_execute (run code in the live page), session_close.

Most of the paid web surface is metered rather than flat: a crawl holds limit credits and refunds every page it did not crawl; a session holds against ttl_seconds and settles on close. Job, monitor, and session management is 0 credits. See socialcrawl_get_docs topic web, or socialcrawl_pricing with platform: "web".

Smart validation

Before making any API call, socialcrawl_request mirrors the backend's own pre-billing validator against the bundled registry data: the platform and resource exist, required parameters and oneOf groups are satisfied, enum values are legal, integers sit inside their declared range, parameter couplings hold (order needs sort; Reddit's timeframe needs sort=top), and CSV lists are within their entry limits. A malformed call fails instantly and for free instead of costing a round trip — and an agent gets told exactly what to fix rather than looping on a call that can never succeed.

Retry-safe requests

Pass an idempotencyKey to socialcrawl_request (UUIDv4 recommended) to make the call retry-safe. If the request is replayed within 24h, the server returns the original response and deducts 0 credits (X-Idempotent-Replay: true).

Supported Platforms

Total: 381 endpoints across 48 platforms.

Error Handling

The MCP server handles errors gracefully and gives the agent actionable guidance:

Links

• Get Your API Key — 100 free credits, no credit card required

• API Documentation — full endpoint reference, credits, and error codes

• SocialCrawl Website

• npm Package

• MCP Registry

• Getting Started Guide

• How It Works