@socialapis/mcp
Advanced tools
MCP server and client for SocialAPIs - Access social media data in Claude, Cursor, and any MCP-compatible tool
Unified social media API for AI agents
Website • Documentation • Discord • npm
Official SDKs: Python • JavaScript / TypeScript • Go
npm install -g @socialapis/mcp
Add to your Claude Desktop config:
macOS:
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows:
notepad %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"socialapis": {
"command": "npx",
"args": ["-y", "@socialapis/mcp", "YOUR_API_KEY"]
}
}
}
# Set environment variable
export SOCIALAPIS_API_KEY=your_api_key_here
# Run without argument
npx @socialapis/mcp
# 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
| 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 |
YOUR_API_KEY in configRestart Claude Desktop and ask:
Get Nike's Facebook page details
47 tools across Facebook and Instagram. Every tool maps 1:1 to a REST endpoint on api.socialapis.io — pricing notes in each tool description indicate per-call credit cost.
facebook_get_page_id — Extract page ID from URLfacebook_get_page_details — Page info, followers, likes, category. Set exact_followers_count=true for the exact integer (charges 5 credits instead of 1)facebook_get_page_posts — Fetch posts with after_time / before_time for date filtering. limit 3-9, charges scale per ceil(returned / 3)facebook_get_page_videos — Page videos, limit 6-12facebook_get_page_reels — Reels / short videosfacebook_get_group_id — Extract group ID from URLfacebook_get_group_details — Full details (members, description, rules)facebook_get_group_posts — Group posts, same limit + date filtering as page postsfacebook_get_group_videos — Group videos with paginationfacebook_get_post_id — Extract post ID from URLfacebook_get_post_details — Reactions, comments count, shares, mediafacebook_get_post_details_extended — Extended fields: view counts (essential for reels / video posts), video URLs, music/audio metadata, author verificationfacebook_get_post_attachments — Full media attachments (5 credits per call)facebook_get_video_details — Video post metadata + statsfacebook_get_post_comments — Top-level comments, limit up to 30facebook_get_comment_replies — Replies to a specific commentfacebook_search_pages — Search pages by keyword + optional location filterfacebook_search_people — Search public profiles by keywordfacebook_search_locations — Look up Facebook location UIDs (for use in other endpoints)facebook_search_posts — Search posts by keyword, recency, locationfacebook_search_videos — Search Facebook Watch videosfacebook_ads_search — Search ads by keyword, country, statusfacebook_ads_page_details — All ads from a specific pagefacebook_ads_archive_details — Full ad archive detailsfacebook_ads_keywords — Search ads by keywordfacebook_ads_countries — List of supported country codesfacebook_marketplace_search — Item search with location, price, category, condition filtersfacebook_marketplace_listing — Single listing detailsfacebook_marketplace_seller — Seller profile + their listingsfacebook_marketplace_categories — Browse category hierarchyfacebook_marketplace_city_coordinates — Lat/long for a city (for radius search)facebook_marketplace_vehicles — Vehicle-specific listing searchfacebook_marketplace_rentals — Rental property listingsfacebook_download_media — Direct download URL for FB media (images, videos)instagram_get_user_id — Resolve username → numeric IDinstagram_get_profile_details — Profile info, follower count, bio, post countinstagram_get_profile_posts — Recent posts from a profileinstagram_get_profile_reels — Reels from a profileinstagram_get_profile_highlights — Story highlights listinstagram_get_highlight_details — Full content of a specific highlightinstagram_get_post_id — Resolve post URL → IDinstagram_get_post_details — Likes, comments, media, captioninstagram_get_reels_feed — Reels feed for a profileinstagram_get_reels_by_audio — Reels using a specific audio/music IDinstagram_popular_search — Trending queries / suggestionsinstagram_get_location_posts — Posts tagged at a specific locationinstagram_get_nearby_locations — Nearby location IDs (for use in location-posts)Track the platform roadmap at socialapis.io/api-sources.
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).
What's Nike's follower count on Facebook?
→ Uses facebook_get_page_details (1 credit)
Get the latest 9 posts from facebook.com/EngenSA
→ Uses facebook_get_page_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_search (1 credit)
Compare engagement on Nike vs Adidas's last 9 Facebook posts
→ Claude calls facebook_get_page_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_get_page_posts (1 credit) then
facebook_get_post_comments 3 times (3 credits) and summarizes.
Show me marketplace listings for "PlayStation 5" under $400 in Berlin
→ Claude calls facebook_marketplace_city_coordinates (1 credit) +
facebook_marketplace_search with filters (1 credit).
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.
Claude Desktop
↓
@socialapis/mcp (local MCP client)
↓
https://mcp.socialapis.io (global proxy)
↓
https://api.socialapis.io (data API)
Why this architecture?
# 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 # Tool definitions
├── mcp-wrapper.js # MCP client (runs locally)
├── server.js # HTTP proxy server
├── package.json
├── Dockerfile
└── README.md
# 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_get_page_details","arguments":{"link":"https://facebook.com/nike"}}'
| Plan | Requests/Month | Price |
|---|---|---|
| Free | 200 | $0 |
| Starter | 30,000 | $49 |
| Pro | 120,000 | $179 |
| Enterprise | Unlimited | Custom |
We welcome contributions! Please see CONTRIBUTING.md for details.
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)Shipped:
@socialapis/mcpsocialapis-sdk on PyPI (51 endpoints, MIT)socialapis-sdk on npm (Node 18+, Bun, Deno, browsers)Upcoming:
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.
This project is licensed under the MIT License - see the LICENSE file for details.
FAQs
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.
Security News
The supply chain control that delays freshly published gems now covers lockfile generation and gem vendoring in Ruby projects.
Security News
During a UK cyber test, a Mythos 5 agent used sockpuppets, social engineering, and prompt injection to try to get a maintainer to merge malware.