socialbridge-mcp
A remote MCP (Model Context Protocol) connector for SocialBridge API — unified social-media data behind one /v1 contract across nine networks (Instagram, TikTok, YouTube, Twitter/X, Reddit, Facebook, Pinterest, Snapchat, Threads; LinkedIn is registered but quarantined). Every network exposes the same four operations — profile, posts, search, comments — returning one flat schema (Profile / Post / Comment) tagged with platform, plus a cross-platform superset (search_all) and a few platform-specific extras.
Live: https://socialbridge-mcp.vercel.app/mcp — 10 tools. Since the upstream SocialBridge deployment is metered (RapidAPI/Apify) and gates every /v1/* route behind a RapidAPI proxy-secret guard, this connector authenticates its own outbound calls with that same secret (SOCIALBRIDGE_MCP_PROXY_SECRET, sent as the X-RapidAPI-Proxy-Secret header) and applies a soft per-IP rate limit (SOCIALBRIDGE_MCP_RATE_LIMIT, default 30 tool-calls/hour, in-memory) so the free MCP tier stays a discovery channel rather than an unmetered bypass of the paid listing — see lib/ratelimit.js.
What this is, and why it's a separate connector
SocialBridge API is a plain REST API. Any HTTP client can already call it directly. This repo exists because MCP clients (Claude, ChatGPT, and other MCP-aware agents) don't consume arbitrary REST APIs — they consume MCP tools. socialbridge-mcp is a thin adapter layer that:
- Exposes each SocialBridge endpoint as a discoverable, typed MCP tool (name, description, zod input schema, annotations) that an LLM can reason about and call directly.
- Speaks the MCP streamable-HTTP transport at a single
/mcpendpoint, so it registers as a connector in Claude, ChatGPT, or any other MCP client with one URL. - Does nothing else. Every tool call is a pass-through
fetchto SocialBridge, and the JSON response is handed back verbatim as the tool result.
Authentication: None on the MCP side (deliberate)
SocialBridge's data has no per-user dimension — it's public social-media metadata (profiles, posts, search results, comments). There is nothing to gate per-caller, so this connector ships with no OAuth, no login, no Supabase, no billing, no demo-vs-real split — every caller gets the same real, live data. api/mcp.js builds a fresh, stateless McpServer per request.
The connector still authenticates its own outbound calls to the metered upstream (see below) — that is a server-to-server detail invisible to MCP callers, not per-caller auth.
Tools
One tool per real SocialBridge /v1 route (from social-api/openapi.yaml + src/routes.js):
| Tool | SocialBridge endpoint | Description |
|---|---|---|
social_profile | GET /v1/{platform}/profile | One account profile as the unified Profile schema. |
social_posts | GET /v1/{platform}/posts | An account's recent posts as the unified Post[]. |
social_search | GET /v1/{platform}/search | Search one network for posts (unified Post[]). |
social_comments | GET /v1/{platform}/comments | Comments/replies on a post (unified Comment[]). |
search_all | GET /v1/search/all | Fan one query across every network in parallel, merged. |
reddit_history | GET /v1/reddit/history | Keyless Reddit full-history pull (Arctic Shift). |
facebook_ads | GET /v1/facebook/ads | Meta Ad Library records as the unified Ad[] (gated). |
youtube_transcript | GET /v1/youtube/transcript | Caption-language list / cue segments for a video. |
threads_post | GET /v1/threads/post | A single thread by shortcode or URL, with replies. |
snapchat_spotlight | GET /v1/snapchat/spotlight | A creator's public Spotlight feed (unified Post[]). |
platform is an enum of instagram, tiktok, youtube, twitter, reddit, facebook, pinterest, snapchat, threads, linkedin. Keyless platforms return real data with no setup; gated platforms return an honest credentials_required and LinkedIn returns platform_disabled — nothing is ever faked.
All 10 tools are read-only and annotated { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }.
Environment variables
| Var | Default | Purpose |
|---|---|---|
SOCIALBRIDGE_MCP_API_BASE_URL | https://social-api-olive.vercel.app | Upstream SocialBridge base URL (override for local/self-hosted testing). |
SOCIALBRIDGE_MCP_PROXY_SECRET | (unset) | RapidAPI proxy secret, sent outbound as X-RapidAPI-Proxy-Secret to pass the upstream /v1/* guard. Without it the upstream returns 403 and tools surface it honestly. |
SOCIALBRIDGE_MCP_RATE_LIMIT | 30 | Soft per-IP cap on tools/call per hour (in-memory, per serverless instance). |
This is a free discovery tier over the metered SocialBridge API — heavy users should go through the paid RapidAPI/Apify listings.
How it wraps social-api
Each tool handler does a plain fetch(\${SOCIALBRIDGE_MCP_API_BASE_URL}${path}`, ...)(with theX-RapidAPI-Proxy-Secret` header when configured) against the real SocialBridge REST API and returns the parsed JSON as MCP tool-result content:
{ content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
Upstream HTTP errors (4xx/5xx) are caught and surfaced as a typed MCP error result via an asError helper rather than crashing the request.
Local development
npm install
node local-server.js & # serves /mcp and /health on :3900
SOCIALBRIDGE_MCP_PROXY_SECRET=... npm run smoke # real end-to-end smoke test