SocialAPIs — Facebook & Instagram Data

SocialAPIs MCP 服务

---

🚀 快速开始

AI Agent（Cline、Claude Code、Cursor）： 按照 llms-install.md 中的步骤完成安装和验证。

一键安装： 点击上方的在 Cursor 中安装按钮，然后在 Cursor 的 MCP 设置中将 YOUR_API_KEY 替换为你的密钥。也可在 Smithery、cursor.directory、mcp.so 和官方 MCP 注册表（io.github.SocialAPIsHub/social-media-api）中找到。

选项 A — 托管（远程 MCP，无需安装）

将任何支持远程 MCP 服务（Streamable HTTP）的客户端指向：

https://mcp.socialapis.io/mcp

在请求头中使用你的 SocialAPIs API 密钥进行身份验证：

Authorization: Bearer YOUR_API_KEY

（x-api-token: YOUR_API_KEY 也可使用。）无需密钥即可列出工具；调用工具则需要密钥。以下是适用于接受 URL 和请求头的客户端的示例配置：

{
  "mcpServers": {
    "socialapis": {
      "url": "https://mcp.socialapis.io/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

选项 B — 本地（npx，stdio）

安装

npm install -g @socialapis/mcp

配置

将以下内容添加到你的 Claude Desktop 配置中：

macOS：

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows：

notepad %APPDATA%\Claude\claude_desktop_config.json

🔧 配置

方法 1：命令行参数（推荐用于 Claude Desktop）

{
  "mcpServers": {
    "socialapis": {
      "command": "npx",
      "args": ["-y", "@socialapis/mcp", "YOUR_API_KEY"]
    }
  }
}

方法 2：环境变量

# Set environment variable
export SOCIALAPIS_API_KEY=your_api_key_here

# Run without argument
npx @socialapis/mcp

方法 3：.env 文件（用于开发）

# Copy example file
cp .env.example .env

# Edit with your values
nano .env

.env 文件：

SOCIALAPIS_API_KEY=your_api_key_here
MCP_PROXY_URL=https://mcp.socialapis.io

环境变量

变量	描述	默认值
SOCIALAPIS_API_KEY	你的 SocialAPIs API 密钥	无（必填）
MCP_PROXY_URL	MCP 代理服务 URL	https://mcp.socialapis.io
PORT	HTTP 服务端口	3001
API_BASE_URL	后端 API URL	https://api.socialapis.io
SOCIALAPIS_CATALOG_URL	服务遵循的实时端点目录（仅服务端）	https://auth.socialapis.io/api/public/endpoints
SOCIALAPIS_CATALOG_REFRESH_MS	重新读取目录（服务端）或工具列表（npm 客户端）的频率	600000（10 分钟）
SOCIALAPIS_LIVE_CATALOG	0 = 始终使用内置定义（仅服务端）	开启

实时目录

价格、描述和参数会随 SocialAPIs API 更新，无需发布新版本。服务会在启动时（超时为 3 秒）及每 10 分钟读取一次公开端点目录，将其与 src/catalogBaseline.json（src/tools.js 编写时依据的目录）进行比较，并仅应用此后发生的变更：新价格会替换工具的 Pricing: 句子，编辑后的描述或参数会替换现有内容，新增和移除的参数会相应增删，已停用端点的操作会显示“当前不可用。”工具和操作名称永远不会更改；新端点也不会成为工具，除非某个版本将其加入。如果无法读取目录，或者某项更改会导致两个操作的参数冲突，则保留上一次正常的定义（最初为随包附带的定义）。GET /health 会显示 catalog: { source, version, fetchedAt, routes }。npm 客户端每 10 分钟重新读取工具列表，并在列表发生变化时发送 notifications/tools/list_changed。

更新 tools.js 以匹配 API 后，刷新基线：node scripts/snapshot-catalog.mjs --from https://auth.socialapis.io/api/public/endpoints（仅限公开字段）。

获取 API 密钥

1. 在 socialapis.io 注册
2. 前往 控制面板
3. 复制 API 密钥
4. 在配置中替换 YOUR_API_KEY

测试

重启 Claude Desktop 并询问：

Get Nike's Facebook page details

---

📋 功能

• 🌐 一个 API 密钥 - 通过统一接口访问 Facebook 和 Instagram
• 🤖 AI 优先 - 为 Claude、Cursor 和 AI Agent 打造
• 📊 丰富的数据 - 帖子、评论、互动指标
• 🔍 高级筛选 - 时间范围、分页
• 🎯 简单的身份验证 - 无需处理复杂的 OAuth
• 🧩 结构化输出 - 每个工具都声明输出架构并返回 { result, creditsCharged, creditsRemaining }，便于 Agent 直接跟踪信用点消耗
• 🛡️ 只读注解 - 所有工具均标记为 readOnlyHint，因此客户端可以跳过确认提示
• ⚡ 快速 - 全球边缘网络
• 🔒 安全 - API 密钥保留在本地

---

🛠️ 可用工具

共 12 个工具，涵盖 Facebook 和 Instagram 上的 50 项操作。每个工具对应一种资源，并接受一个 action 参数；每项操作都对应 api.socialapis.io 上的一个 REST 端点。工具说明列出了每项操作、所需参数及其积分成本。

工具	操作
facebook_page	details（粉丝数、联系信息、类别；exact_followers_count=true 需 5 个积分）、id、posts（limit 为 3-9，可按日期筛选）、videos（limit 为 6-12）、reels、albums（profile_id 取自 id，limit 为 8-16）、album_items（相册中的照片和视频）
facebook_group	details、id、posts（limit 为 3-9，可按日期筛选）、videos、albums（group_id 取自 id，limit 为 8-16）、album_items
facebook_post	details、details_extended（浏览量、视频 URL、音频元数据）、id、attachments（5 个积分）、video、comments、comment_replies
facebook_search	pages、people、posts、videos、locations（为其他搜索提供位置 UID）
facebook_ads	search（按关键词、主页、国家/地区、状态搜索广告）、keywords（某个关键词对应的广告主）、page_details、archive_details、countries
facebook_marketplace	search（可按价格、位置、类别、商品状况筛选）、vehicles、rentals、listing、seller、categories、city_coordinates
facebook_media_download	获取 Facebook 图片和视频的下载 URL
instagram_profile	details、id、posts、reels、highlights、highlight_details
instagram_post	details、id（帖子 URL 中的短代码）
instagram_reels	feed、by_audio
instagram_search	按关键词搜索热门用户、主题标签和地点
instagram_location	posts（最新或热门帖子）、nearby

调用示例：使用 facebook_page 并传入 {"action": "posts", "link": "https://www.facebook.com/nike", "limit": 9}。

从 1.x 升级： 以前按端点命名的工具（facebook_get_page_details、instagram_get_profile_posts 等）在直接调用时仍然有效，因此现有提示词和脚本可以继续运行。这些工具不再列出。如果你的客户端会按名称自动批准工具，请添加新的名称。

暂不支持

目前仅支持 Facebook 和 Instagram。TikTok、X / Twitter、LinkedIn 和 YouTube 已列入路线图，但尚无确定日期——这些平台的工具只会在正式发布后才会显示在此处。

在 socialapis.io/api-sources 查看平台路线图。

---

💡 使用示例

以下每个提示词都来自真实的 Claude Desktop 会话。有些属于单次工具调用模式（“帮我获取 X”）；有些需要 Claude 串联多次调用并汇总结果（相关说明见下文）。

单次调用模式（快速、实惠）

What's Nike's follower count on Facebook?
→ Uses facebook_page action=details (1 credit)

Get the latest 9 posts from facebook.com/EngenSA
→ Uses facebook_page action=posts with limit=9 (1-3 credits depending on actual returned count)

Show me the Meta ads currently running for "Apple Vision Pro" in Germany
→ Uses facebook_ads action=search (1 credit)

多次调用模式（由 Claude 协调，但速度较慢且成本较高）

Compare engagement on Nike vs Adidas's last 9 Facebook posts
→ Claude calls facebook_page action=posts twice (~2-6 credits total),
  aggregates reactions/comments/shares per post, returns a comparison.

What are people saying in the comments on Coca-Cola's last 3 posts?
→ Claude calls facebook_page action=posts (1 credit) then
  facebook_post action=comments 3 times (3 credits) and summarizes.

Show me marketplace listings for "PlayStation 5" under $400 in Berlin
→ Claude calls facebook_marketplace action=city_coordinates (1 credit) +
  facebook_marketplace action=search with filters (1 credit).

此 MCP 服务不会做什么

有些查询在聊天中听起来很自然（“比较上个月的互动情况”），但需要 API 尚未提供单个工具支持的聚合计算。Claude 仍然可以回答这些问题，但会调用大量工具，这既慢又昂贵。

查询类型	难点
某个主页“过去 30 天的互动率”	需要获取日期范围内的每篇帖子（分页获取，每次调用的 limit 上限为 9），并计算每篇帖子的互动率。在活跃主页上，这会耗尽 LLM 的工具调用预算。
“比较品牌 A、B、C 上个月的互动率”	问题相同，但需要做 3 次——每个品牌分页获取一次，然后进行比较计算。小时间范围内可行；对于高流量主页的“上个月”数据，则会很慢。
超出 Facebook 自身提供范围的历史归档	我们展示 Facebook 公开可见的内容。已从 Facebook 可见动态中划出的帖子无法检索。
服务端时间序列（每日互动、每周增长）	目前尚不支持，已列入路线图，未来将提供内置聚合功能的 engagement-stats 端点。

如果你的使用场景符合以上某种模式，并且希望预先计算聚合结果，而不是由 LLM 编排完成，请携带具体查询联系支持团队——我们会根据客户需求确定聚合端点的优先级。

---

🏗️ 架构

Claude Desktop
    ↓
@socialapis/mcp (local MCP client)
    ↓
https://mcp.socialapis.io (global proxy)
    ↓
https://api.socialapis.io (data API)

为什么采用这种架构？

• ✅ 延迟低（全球边缘网络）
• ✅ 高可靠性（99.9% 的正常运行时间）
• ✅ 自动速率限制
• ✅ 智能缓存
• ✅ 你的 API 密钥保留在本地

---

🔧 开发

本地设置

# Clone repository
git clone https://github.com/SocialAPIsHub/mcp-server.git
cd mcp-server

# Install dependencies
npm install

# Run MCP client
npm start YOUR_API_KEY

# Run HTTP proxy server
npm run serve

项目结构

mcp-server/
├── src/
│   ├── tools.js          # The 50 endpoint definitions (one per action)
│   ├── groups.js         # Groups them into the 12 listed tools
│   ├── catalogBaseline.json  # The API catalog tools.js was written against
│   ├── catalogOverlay.js # Applies live catalog changes to the definitions
│   └── liveCatalog.js    # Fetches the live catalog (startup + every 10 min)
├── scripts/snapshot-catalog.mjs  # Rewrites catalogBaseline.json
├── test/                 # node --test (npm run test:unit)
├── mcp-wrapper.js        # MCP client (runs locally)
├── server.js             # HTTP proxy server
├── package.json
├── Dockerfile
└── README.md

测试

# Unit tests
npm run test:unit

# Test MCP client locally
node mcp-wrapper.js YOUR_API_KEY

# Test HTTP proxy
curl http://localhost:3001/health
curl http://localhost:3001/tools

# Test specific tool
curl -X POST http://localhost:3001/proxy \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"facebook_page","arguments":{"action":"details","link":"https://facebook.com/nike"}}'

---

📊 定价

套餐	每月积分	价格
免费	200	$0
Pro	1,500	$4.99
Ultra	30,000	$49
Mega	120,000	$179
Enterprise	自定义	联系我们

大多数工具每次调用消耗 1 个积分；每个工具的说明中都会注明确切价格。当前套餐：socialapis.io/pricing。

查看详细定价 →

---

🤝 贡献

欢迎贡献！详情请参阅 CONTRIBUTING.md。

快速贡献指南

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

---

📖 文档

• 完整文档
• API 参考
• MCP 指南
• 示例
• Agent 技能：帮助 Claude Code、Cursor、Codex 和其他编码 Agent 使用 SocialAPIs（npx skills add SocialAPIsHub/skills）

---

💬 支持

• 📧 电子邮件： [email protected]
• 💬 Discord： discord.gg/D5bQskrwV
• 🐛 问题反馈： GitHub Issues
• 📚 文档： docs.socialapis.io

---

🗺️ 路线图

已发布：

• 支持 Facebook API — 7 个工具、37 个操作（主页、群组、帖子、搜索、广告资料库、Marketplace、媒体）
• 支持 Instagram — 5 个工具、13 个操作（个人资料、帖子、Reels、精选动态、发现 / 地点）
• MCP 服务实现
• HTTP 代理服务
• 已发布 npm 包 — @socialapis/mcp
• MCP Registry 收录 — registry.modelcontextprotocol.io
• Python SDK — PyPI 上的 socialapis-sdk（50 个端点，MIT）
• JavaScript / TypeScript SDK — npm 上的 socialapis-sdk（Node 18+、Bun、Deno、浏览器）
• Go SDK — github.com/SocialAPIsHub/socialapis-go（符合 Go 惯例、零依赖）
• Agent 技能 — github.com/SocialAPIsHub/skills，适用于 Claude Code、Cursor、Codex 和其他编码 Agent

即将推出：

• 支持 TikTok
• 支持 X（Twitter）
• 支持 LinkedIn
• 支持 YouTube
• 高级分析 — 服务端聚合端点（随时间变化的互动数据、品牌对比），将多次调用模式简化为一次工具调用
• 实时 Webhook — 新帖子 / 互动达到阈值时推送通知
• 集成 LangChain

平台优先级会根据客户需求调整。要最快推动某项功能进入开发队列，请发送邮件至 [email protected]，或在 Telegram 上私信 @socialapis，并说明使用场景。

---

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

---

🙏 致谢

• 基于 Model Context Protocol 构建
• 由 Anthropic Claude 提供支持
• 灵感来自 AI Agent 社区

---

📇 收录于

还收录于 Official MCP Registry、Smithery、LobeHub、mcp.so、mcpservers.org、cursor.directory 和 awesome-remote-mcp-servers。

---

🌟 星标历史

---