SocialAPIs

SocialAPIs MCP Server

Facebook & Instagram data for AI agents — local (npx) or hosted (remote MCP)

Website • Documentation • Discord • npm

Official SDKs: Python • JavaScript / TypeScript • Go

🚀 Quick Start

AI agents (Cline, Claude Code, Cursor): follow llms-install.md for step-by-step install and verification.

One-click: use the Install in Cursor button above — then replace YOUR_API_KEY in Cursor's MCP settings with your key. Also listed on Smithery, cursor.directory, mcp.so and the official MCP Registry (io.github.SocialAPIsHub/social-media-api).

Option A — Hosted (remote MCP, no install)

Point any client that supports remote MCP servers (Streamable HTTP) at:

https://mcp.socialapis.io/mcp

Authenticate with your SocialAPIs API key in a header:

Authorization: Bearer YOUR_API_KEY

(x-api-token: YOUR_API_KEY also works.) Tool listing works without a key; tool calls need one. Example config for clients that take a URL + headers:

{

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

Option B — Local (npx, stdio)

Installation

npm install -g @socialapis/mcp

Configuration

Add to your Claude Desktop config:

macOS:

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

Windows:

notepad %APPDATA%\Claude\claude_desktop_config.json

🔧 Configuration

Method 1: Command Line Argument (Recommended for Claude Desktop)

{

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

Method 2: Environment Variable

# Set environment variable

export SOCIALAPIS_API_KEY=your_api_key_here

Run without argument

npx @socialapis/mcp

Method 3: .env File (For Development)

# Copy example file

cp .env.example .env

Edit with your values

nano .env

.env file:

SOCIALAPIS_API_KEY=your_api_key_here

MCP_PROXY_URL=https://mcp.socialapis.io

Environment Variables

Live catalog

Prices, descriptions and parameters follow the SocialAPIs API without a new release. The server reads the public endpoint catalog at startup (3 s timeout) and every 10 minutes, compares it with src/catalogBaseline.json (the catalog src/tools.js was written against) and applies only what changed since: a new price replaces the tool's Pricing: sentence, an edited description or parameter replaces ours, added and removed parameters are added and removed, and a disabled endpoint's action says "Currently unavailable." Tool and action names never change, and new endpoints don't become tools until a release adds them. If the catalog can't be read, or a change would make two actions' parameters conflict, the last good definitions (at first the bundled ones) stay. GET /health shows catalog: { source, version, fetchedAt, routes }. The npm client re-reads the tool list every 10 minutes and sends notifications/tools/list_changed when it changes.

After updating tools.js to match the API, refresh the baseline: node scripts/snapshot-catalog.mjs --from https://auth.socialapis.io/api/public/endpoints (public fields only).

Get API Key

1. Sign up at socialapis.io
2. Go to Dashboard
3. Copy your API key
4. Replace YOUR_API_KEY in config

Test It

Restart Claude Desktop and ask:

Get Nike's Facebook page details

📋 Features

• 🌐 One API key - Facebook and Instagram behind a single interface
• 🤖 AI-First - Built for Claude, Cursor, and AI agents
• 📊 Rich Data - Posts, comments, engagement metrics
• 🔍 Advanced Filtering - Time ranges, pagination
• 🎯 Simple Auth - No OAuth complexity
• 🧩 Structured output - every tool declares an output schema and returns { result, creditsCharged, creditsRemaining }, so agents can track credit spend directly
• 🛡️ Read-only annotations - all tools are marked readOnlyHint, so clients can skip confirmation prompts
• ⚡ Fast - Global edge network
• 🔒 Secure - API keys stay local

🛠️ Available Tools

12 tools covering 50 actions across Facebook and Instagram. Each tool groups one resource and takes an action argument; every action maps to one REST endpoint on api.socialapis.io. Tool descriptions list each action, the parameters it needs and its credit cost.

Example call: facebook_page with {"action": "posts", "link": "https://www.facebook.com/nike", "limit": 9}.

Upgrading from 1.x: the earlier per-endpoint tool names (facebook_get_page_details, instagram_get_profile_posts, …) still work when called directly, so existing prompts and scripts keep running. They're no longer listed. If your client auto-approves tools by name, add the new names.

Not supported yet

Only Facebook and Instagram are live today. TikTok, X / Twitter, LinkedIn and YouTube are on the roadmap with no committed dates — tools for them will appear here only once they ship.

Track the platform roadmap at socialapis.io/api-sources.

💡 Usage examples

Each prompt below is a real Claude Desktop session. Some of these are single-tool-call patterns ("get me X"); some require Claude to chain multiple calls + aggregate the results (noted where).

Single-call patterns (fast, cheap)

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)

Multi-call patterns (Claude orchestrates these — but it's slower + more expensive)

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).

What this MCP server does NOT do

Some queries look natural in a chat ("compare engagement over the last month") but require aggregations the API doesn't expose as a single tool yet. Claude can still answer them, but it'll fan out into many tool calls — which is slow + expensive.

If your use case maps to one of these patterns and you want the aggregation pre-computed instead of LLM-orchestrated, contact support with the specific query — we're prioritizing the aggregation endpoint based on customer demand.

🏗️ Architecture

Claude Desktop

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

Why this architecture?

• ✅ Low latency (global edge network)
• ✅ High reliability (99.9% uptime)
• ✅ Auto rate limiting
• ✅ Smart caching
• ✅ Your API key stays local

🔧 Development

Local Setup

# Clone repository

git clone https://github.com/SocialAPIsHub/mc