io.github.IsaiahDupree/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):

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

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 the X-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