socialbridge-mcp

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 /mcp endpoint, 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 fetch to 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