socialbridge-mcp

socialbridge-mcp

面向 SocialBridge API 的远程 **MCP（Model Context Protocol）**连接器——通过统一的 /v1 契约，提供覆盖九个社交网络的数据（Instagram、TikTok、YouTube、Twitter/X、Reddit、Facebook、Pinterest、Snapchat、Threads；LinkedIn 已注册，但处于隔离状态）。每个网络都提供相同的四种操作——profile、posts、search、comments——并返回带有 platform 标签的扁平统一架构（Profile / Post / Comment），此外还提供跨平台的超集操作（search_all）和少数平台专属功能。

线上服务：https://socialbridge-mcp.vercel.app/mcp——10 个工具。由于上游 SocialBridge 部署按量计费（RapidAPI/Apify），且所有 /v1/* 路由都受 RapidAPI 代理密钥保护，此连接器使用相同的密钥对自己的出站调用进行身份验证（将 SOCIALBRIDGE_MCP_PROXY_SECRET 作为 X-RapidAPI-Proxy-Secret 标头发送），并实施软性 IP 速率限制（SOCIALBRIDGE_MCP_RATE_LIMIT，默认每小时 30 次工具调用，使用内存存储），以确保免费的 MCP 层仅用于发现服务，而不是绕过付费服务的无限制通道——请参阅 lib/ratelimit.js。

这是什么，为什么它是独立的连接器

SocialBridge API 是一个普通的 REST API。任何 HTTP 客户端都可以直接调用它。本仓库之所以存在，是因为MCP 客户端（Claude、ChatGPT 及其他支持 MCP 的 Agent）不会使用任意 REST API——它们使用 MCP 工具。socialbridge-mcp 是一个轻量级适配层，用于：

• 将每个 SocialBridge 端点公开为可发现、经过类型定义的 MCP 工具（名称、描述、zod 输入架构、注解），供大模型推理并直接调用。
• 通过单一的 /mcp 端点使用 MCP 可流式 HTTP传输，因此只需一个 URL，即可在 Claude、ChatGPT 或任何其他 MCP 客户端中注册为连接器。
• 不做其他任何事情。每次工具调用都会透传为对 SocialBridge 的 fetch 请求，并将 JSON 响应原样作为工具结果返回。

身份验证：MCP 端无需身份验证（有意为之）

SocialBridge 的数据没有按用户区分的维度——它是公开的社交媒体元数据（个人资料、帖子、搜索结果、评论）。没有需要按调用者进行限制的内容，因此此连接器不提供 OAuth、登录、Supabase、计费，也不区分演示数据和真实数据——所有调用者都会获得相同的实时真实数据。api/mcp.js 会为每个请求创建一个全新的无状态 McpServer。

此连接器仍会对发往按量计费上游服务的出站调用进行身份验证（见下文）——这是服务器到服务器的细节，MCP 调用者不可见，并非针对单个调用者的身份验证。

工具

每个真实的 SocialBridge /v1 路由对应一个工具（来自 social-api/openapi.yaml + src/routes.js）：

工具	SocialBridge 端点	描述
social_profile	GET /v1/{platform}/profile	将单个账号的个人资料作为统一的 Profile 架构返回。
social_posts	GET /v1/{platform}/posts	将账号的近期帖子作为统一的 Post[] 返回。
social_search	GET /v1/{platform}/search	在一个社交网络中搜索帖子（统一的 Post[]）。
social_comments	GET /v1/{platform}/comments	帖子上的评论/回复（统一的 Comment[]）。
search_all	GET /v1/search/all	并行地将一个查询分发到所有社交网络，并合并结果。
reddit_history	GET /v1/reddit/history	无需密钥的 Reddit 全部历史记录拉取（Arctic Shift）。
facebook_ads	GET /v1/facebook/ads	将 Meta 广告资料作为统一的 Ad[] 返回（受限）。
youtube_transcript	GET /v1/youtube/transcript	返回视频的字幕语言列表/字幕片段。
threads_post	GET /v1/threads/post	根据 shortcode 或 URL 获取单个帖子及其回复。
snapchat_spotlight	GET /v1/snapchat/spotlight	创作者的公开 Spotlight 信息流（统一的 Post[]）。

platform 是一个枚举，包括 instagram, tiktok, youtube, twitter, reddit, facebook, pinterest, snapchat, threads, linkedin。无需密钥的平台无需设置即可返回真实数据；受限平台会如实返回 credentials_required，LinkedIn 则会返回 platform_disabled——绝不会伪造数据。

全部 10 个工具均为只读工具，并标注为 { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }。

环境变量

变量	默认值	用途
SOCIALBRIDGE_MCP_API_BASE_URL	https://social-api-olive.vercel.app	上游 SocialBridge 基础 URL（可覆盖，以便进行本地/自托管测试）。
SOCIALBRIDGE_MCP_PROXY_SECRET	(未设置)	RapidAPI 代理密钥，作为 X-RapidAPI-Proxy-Secret 随请求发送，以通过上游 /v1/* 防护。未设置时，上游会返回 403，工具也会如实显示该结果。
SOCIALBRIDGE_MCP_RATE_LIMIT	30	tools/call 每小时的软性单 IP 限额（内存存储，按无服务器实例计算）。

这是基于按量计费的 SocialBridge API 提供的免费探索层——重度用户应使用付费 RapidAPI/Apify 列表。

它如何封装 social-api

每个工具处理程序都会针对真实的 SocialBridge REST API 执行普通的 fetch(\${SOCIALBRIDGE_MCP_API_BASE_URL}${path}`, ...)（配置后会附带 X-RapidAPI-Proxy-Secret` 标头），并将解析后的 JSON 作为 MCP 工具结果内容返回：

{ content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }

上游 HTTP 错误（4xx/5xx）会被捕获，并通过 asError 辅助函数作为类型化的 MCP 错误结果显示，而不会导致请求崩溃。

本地开发

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