SocialAPIs MCP Server

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

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

Variable	Description	Default
`SOCIALAPIS_API_KEY`	Your SocialAPIs API key	None (required)
`MCP_PROXY_URL`	MCP proxy server URL	`https://mcp.socialapis.io`
`PORT`	HTTP server port	`3001`
`API_BASE_URL`	Backend API URL	`https://api.socialapis.io`
`SOCIALAPIS_CATALOG_URL`	Live endpoint catalog the server follows (server only)	`https://auth.socialapis.io/api/public/endpoints`
`SOCIALAPIS_CATALOG_REFRESH_MS`	How often the catalog (server) or tool list (npm client) is re-read	`600000` (10 min)
`SOCIALAPIS_LIVE_CATALOG`	`0` = always use the bundled definitions (server only)	on

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

Sign up at socialapis.io
Go to Dashboard
Copy your API key
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.

Tool	Actions
`facebook_page`	`details` (followers, contact info, category; `exact_followers_count=true` costs 5 credits), `id`, `posts` (`limit` 3-9, date filters), `videos` (`limit` 6-12), `reels`, `albums` (`profile_id` from `id`, `limit` 8-16), `album_items` (photos and videos in an album)
`facebook_group`	`details`, `id`, `posts` (`limit` 3-9, date filters), `videos`, `albums` (`group_id` from `id`, `limit` 8-16), `album_items`
`facebook_post`	`details`, `details_extended` (view counts, video URLs, audio metadata), `id`, `attachments` (5 credits), `video`, `comments`, `comment_replies`
`facebook_search`	`pages`, `people`, `posts`, `videos`, `locations` (location UIDs for the other searches)
`facebook_ads`	`search` (ads by keyword, page, country, status), `keywords` (advertisers for a keyword), `page_details`, `archive_details`, `countries`
`facebook_marketplace`	`search` (price, location, category, condition filters), `vehicles`, `rentals`, `listing`, `seller`, `categories`, `city_coordinates`
`facebook_media_download`	Download URLs for Facebook images and videos
`instagram_profile`	`details`, `id`, `posts`, `reels`, `highlights`, `highlight_details`
`instagram_post`	`details`, `id` (shortcode from a post URL)
`instagram_reels`	`feed`, `by_audio`
`instagram_search`	Popular users, hashtags and places for a keyword
`instagram_location`	`posts` (recent or top), `nearby`

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.

Query shape	Why it's hard
"Engagement rate over the last 30 days" for a page	Requires fetching every post in the date range (paginated, `limit` capped at 9 per call) and computing engagement per post. Hits the LLM tool-call budget on busy pages.
"Compare engagement rates between Brand A, B, C over the last month"	Same problem, 3× — one paginated fetch per brand, then comparison math. Works for small windows; slow for "last month" on high-volume pages.
Historical archive older than what Facebook itself serves	We surface what Facebook makes publicly visible. Posts that scrolled off Facebook's visible feed aren't retrievable.
Server-side time-series (daily engagement, weekly growth)	Not yet — on the roadmap as a future `engagement-stats` endpoint with built-in aggregation.

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/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

Project Structure

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

Testing

# 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"}}'

📊 Pricing

Plan	Credits / month	Price
Free	200	$0
Pro	1,500	$4.99
Ultra	30,000	$49
Mega	120,000	$179
Enterprise	Custom	Contact us

Most tools cost 1 credit per call; each tool description states its exact price. Current plans: socialapis.io/pricing.

View detailed pricing →

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Quick Contribution Guide

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📖 Documentation

Full Documentation
API Reference
MCP Guide
Examples
Agent skill: teaches Claude Code, Cursor, Codex and other coding agents to use SocialAPIs (npx skills add SocialAPIsHub/skills)

💬 Support

📧 Email: support@socialapis.io
💬 Discord: discord.gg/D5bQskrwV
🐛 Issues: GitHub Issues
📚 Docs: docs.socialapis.io

🗺️ Roadmap

Shipped:

Upcoming:

TikTok support
X (Twitter) support
LinkedIn support
YouTube support
Advanced analytics — server-side aggregation endpoints (engagement-over-time, brand comparisons) so multi-call patterns become a single tool call
Real-time webhooks — push notifications on new posts / engagement thresholds
LangChain integration

Platform priorities shift based on customer demand. The fastest way to push something up the queue is to email support@socialapis.io or DM @socialapis on Telegram with the use case.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with Model Context Protocol
Powered by Anthropic Claude
Inspired by the AI agent community

📇 Listed on

Also on the Official MCP Registry, Smithery, LobeHub, mcp.so, mcpservers.org, cursor.directory and awesome-remote-mcp-servers.

🌟 Star History

Made with ❤️ by the SocialAPIs Team

Website • Twitter • Discord

Python SDK • JS SDK • Go SDK

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
assets		assets
scripts		scripts
src		src
test		test
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
glama.json		glama.json
lhm.plugin.json		lhm.plugin.json
llms-install.md		llms-install.md
mcp-wrapper.js		mcp-wrapper.js
mcp.json		mcp.json
package.json		package.json
plugin.json		plugin.json
server.js		server.js
server.json		server.json

Latest commit

History

Folders and files

Repository files navigation