{
  "markdown": "# SocialAPIs MCP Server\n\n<div align=\"center\">\n\n![SocialAPIs Logo](https://socialapis.io/logo.png)\n\n**Unified social media API for AI agents**\n\n[![npm version](https://badge.fury.io/js/%40socialapis%2Fmcp.svg)](https://www.npmjs.com/package/@socialapis/mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub stars](https://img.shields.io/github/stars/SocialAPIsHub/mcp-server.svg)](https://github.com/SocialAPIsHub/mcp-server/stargazers)\n\n[Website](https://socialapis.io) • [Documentation](https://docs.socialapis.io) • [Discord](https://discord.gg/D5bQskrwV) • [npm](https://www.npmjs.com/package/@socialapis/mcp)\n\n**Official SDKs:** [Python](https://pypi.org/project/socialapis-sdk/) • [JavaScript / TypeScript](https://www.npmjs.com/package/socialapis-sdk) • [Go](https://github.com/SocialAPIsHub/socialapis-go)\n\n</div>\n\n---\n\n## 🚀 Quick Start\n\n### Installation\n```bash\nnpm install -g @socialapis/mcp\n```\n\n### Configuration\n\nAdd to your Claude Desktop config:\n\n**macOS:**\n```bash\nnano ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n```\n\n**Windows:**\n```powershell\nnotepad %APPDATA%\\Claude\\claude_desktop_config.json\n```\n\n## 🔧 Configuration\n\n### Method 1: Command Line Argument (Recommended for Claude Desktop)\n```json\n{\n  \"mcpServers\": {\n    \"socialapis\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@socialapis/mcp\", \"YOUR_API_KEY\"]\n    }\n  }\n}\n```\n\n### Method 2: Environment Variable\n```bash\n# Set environment variable\nexport SOCIALAPIS_API_KEY=your_api_key_here\n\n# Run without argument\nnpx @socialapis/mcp\n```\n\n### Method 3: .env File (For Development)\n```bash\n# Copy example file\ncp .env.example .env\n\n# Edit with your values\nnano .env\n```\n\n**.env file:**\n```properties\nSOCIALAPIS_API_KEY=your_api_key_here\nMCP_PROXY_URL=https://mcp.socialapis.io\n```\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `SOCIALAPIS_API_KEY` | Your SocialAPIs API key | None (required) |\n| `MCP_PROXY_URL` | MCP proxy server URL | `https://mcp.socialapis.io` |\n| `PORT` | HTTP server port | `3001` |\n| `API_BASE_URL` | Backend API URL | `https://api.socialapis.io` |\n\n### Get API Key\n\n1. Sign up at [socialapis.io](https://socialapis.io)\n2. Go to [Dashboard](https://socialapis.io/dashboard)\n3. Copy your API key\n4. Replace `YOUR_API_KEY` in config\n\n### Test It\n\nRestart Claude Desktop and ask:\n```\nGet Nike's Facebook page details\n```\n\n---\n\n## 📋 Features\n\n- 🌐 **Unified API** - One interface for multiple platforms\n- 🤖 **AI-First** - Built for Claude, Cursor, and AI agents\n- 📊 **Rich Data** - Posts, comments, engagement metrics\n- 🔍 **Advanced Filtering** - Time ranges, pagination\n- 🎯 **Simple Auth** - No OAuth complexity\n- ⚡ **Fast** - Global edge network\n- 🔒 **Secure** - API keys stay local\n\n---\n\n## 🛠️ Available Tools\n\n47 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.\n\n### Facebook — Pages\n- `facebook_get_page_id` — Extract page ID from URL\n- `facebook_get_page_details` — Page info, followers, likes, category. Set `exact_followers_count=true` for the exact integer (charges 5 credits instead of 1)\n- `facebook_get_page_posts` — Fetch posts with `after_time` / `before_time` for date filtering. `limit` 3-9, charges scale per `ceil(returned / 3)`\n- `facebook_get_page_videos` — Page videos, `limit` 6-12\n- `facebook_get_page_reels` — Reels / short videos\n\n### Facebook — Groups\n- `facebook_get_group_id` — Extract group ID from URL\n- `facebook_get_group_details` — Full details (members, description, rules)\n- `facebook_get_group_posts` — Group posts, same `limit` + date filtering as page posts\n- `facebook_get_group_videos` — Group videos with pagination\n\n### Facebook — Posts\n- `facebook_get_post_id` — Extract post ID from URL\n- `facebook_get_post_details` — Reactions, comments count, shares, media\n- `facebook_get_post_details_extended` — Extended fields: **view counts** (essential for reels / video posts), video URLs, music/audio metadata, author verification\n- `facebook_get_post_attachments` — Full media attachments (5 credits per call)\n- `facebook_get_video_details` — Video post metadata + stats\n- `facebook_get_post_comments` — Top-level comments, `limit` up to 30\n- `facebook_get_comment_replies` — Replies to a specific comment\n\n### Facebook — Search\n- `facebook_search_pages` — Search pages by keyword + optional location filter\n- `facebook_search_people` — Search public profiles by keyword\n- `facebook_search_locations` — Look up Facebook location UIDs (for use in other endpoints)\n- `facebook_search_posts` — Search posts by keyword, recency, location\n- `facebook_search_videos` — Search Facebook Watch videos\n\n### Facebook — Ads Library (Meta Ad Transparency)\n- `facebook_ads_search` — Search ads by keyword, country, status\n- `facebook_ads_page_details` — All ads from a specific page\n- `facebook_ads_archive_details` — Full ad archive details\n- `facebook_ads_keywords` — Search ads by keyword\n- `facebook_ads_countries` — List of supported country codes\n\n### Facebook — Marketplace\n- `facebook_marketplace_search` — Item search with location, price, category, condition filters\n- `facebook_marketplace_listing` — Single listing details\n- `facebook_marketplace_seller` — Seller profile + their listings\n- `facebook_marketplace_categories` — Browse category hierarchy\n- `facebook_marketplace_city_coordinates` — Lat/long for a city (for radius search)\n- `facebook_marketplace_vehicles` — Vehicle-specific listing search\n- `facebook_marketplace_rentals` — Rental property listings\n\n### Facebook — Media\n- `facebook_download_media` — Direct download URL for FB media (images, videos)\n\n### Instagram — Profile\n- `instagram_get_user_id` — Resolve username → numeric ID\n- `instagram_get_profile_details` — Profile info, follower count, bio, post count\n- `instagram_get_profile_posts` — Recent posts from a profile\n- `instagram_get_profile_reels` — Reels from a profile\n- `instagram_get_profile_highlights` — Story highlights list\n- `instagram_get_highlight_details` — Full content of a specific highlight\n\n### Instagram — Posts + Reels\n- `instagram_get_post_id` — Resolve post URL → ID\n- `instagram_get_post_details` — Likes, comments, media, caption\n- `instagram_get_reels_feed` — Reels feed for a profile\n- `instagram_get_reels_by_audio` — Reels using a specific audio/music ID\n\n### Instagram — Discovery\n- `instagram_popular_search` — Trending queries / suggestions\n- `instagram_get_location_posts` — Posts tagged at a specific location\n- `instagram_get_nearby_locations` — Nearby location IDs (for use in location-posts)\n\n### Coming soon\n- TikTok (videos, profiles, hashtags)\n- X / Twitter (tweets, profiles, search)\n- LinkedIn (company pages, posts, employees)\n- YouTube (videos, channels, comments)\n\nTrack the platform roadmap at [socialapis.io/api-sources](https://socialapis.io/api-sources).\n\n---\n\n## 💡 Usage examples\n\nEach 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).\n\n### Single-call patterns (fast, cheap)\n\n```\nWhat's Nike's follower count on Facebook?\n→ Uses facebook_get_page_details (1 credit)\n\nGet the latest 9 posts from facebook.com/EngenSA\n→ Uses facebook_get_page_posts with limit=9 (1-3 credits depending on actual returned count)\n\nShow me the Meta ads currently running for \"Apple Vision Pro\" in Germany\n→ Uses facebook_ads_search (1 credit)\n```\n\n### Multi-call patterns (Claude orchestrates these — but it's slower + more expensive)\n\n```\nCompare engagement on Nike vs Adidas's last 9 Facebook posts\n→ Claude calls facebook_get_page_posts twice (~2-6 credits total),\n  aggregates reactions/comments/shares per post, returns a comparison.\n\nWhat are people saying in the comments on Coca-Cola's last 3 posts?\n→ Claude calls facebook_get_page_posts (1 credit) then\n  facebook_get_post_comments 3 times (3 credits) and summarizes.\n\nShow me marketplace listings for \"PlayStation 5\" under $400 in Berlin\n→ Claude calls facebook_marketplace_city_coordinates (1 credit) +\n  facebook_marketplace_search with filters (1 credit).\n```\n\n### What this MCP server does NOT do\n\nSome 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.\n\n| Query shape | Why it's hard |\n|---|---|\n| \"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. |\n| \"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. |\n| 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. |\n| Server-side time-series (daily engagement, weekly growth) | Not yet — on the roadmap as a future `engagement-stats` endpoint with built-in aggregation. |\n\nIf your use case maps to one of these patterns and you want the aggregation pre-computed instead of LLM-orchestrated, [contact support](https://socialapis.io/contact-us) with the specific query — we're prioritizing the aggregation endpoint based on customer demand.\n\n---\n\n## 🏗️ Architecture\n```\nClaude Desktop\n    ↓\n@socialapis/mcp (local MCP client)\n    ↓\nhttps://mcp.socialapis.io (global proxy)\n    ↓\nhttps://api.socialapis.io (data API)\n```\n\n**Why this architecture?**\n- ✅ Low latency (global edge network)\n- ✅ High reliability (99.9% uptime)\n- ✅ Auto rate limiting\n- ✅ Smart caching\n- ✅ Your API key stays local\n\n---\n\n## 🔧 Development\n\n### Local Setup\n```bash\n# Clone repository\ngit clone https://github.com/SocialAPIsHub/mcp-server.git\ncd mcp-server\n\n# Install dependencies\nnpm install\n\n# Run MCP client\nnpm start YOUR_API_KEY\n\n# Run HTTP proxy server\nnpm run serve\n```\n\n### Project Structure\n```\nmcp-server/\n├── src/\n│   └── tools.js          # Tool definitions\n├── mcp-wrapper.js        # MCP client (runs locally)\n├── server.js             # HTTP proxy server\n├── package.json\n├── Dockerfile\n└── README.md\n```\n\n### Testing\n```bash\n# Test MCP client locally\nnode mcp-wrapper.js YOUR_API_KEY\n\n# Test HTTP proxy\ncurl http://localhost:3001/health\ncurl http://localhost:3001/tools\n\n# Test specific tool\ncurl -X POST http://localhost:3001/proxy \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"tool\":\"facebook_get_page_details\",\"arguments\":{\"link\":\"https://facebook.com/nike\"}}'\n```\n\n---\n\n## 📊 Pricing\n\n| Plan | Requests/Month | Price |\n|------|----------------|-------|\n| **Free** | 200 | $0 |\n| **Starter** | 30,000 | $49 |\n| **Pro** | 120,000 | $179 |\n| **Enterprise** | Unlimited | Custom |\n\n[View detailed pricing →](https://socialapis.io/pricing)\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n### Quick Contribution Guide\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n---\n\n## 📖 Documentation\n\n- [Full Documentation](https://docs.socialapis.io)\n- [API Reference](https://docs.socialapis.io/api-reference/facebook)\n- [MCP Guide](https://docs.socialapis.io/mcp)\n- [Examples](https://github.com/SocialAPIsHub/examples)\n\n---\n\n## 💬 Support\n\n- 📧 **Email:** [support@socialapis.io](mailto:support@socialapis.io)\n- 💬 **Discord:** [discord.gg/D5bQskrwV](https://discord.gg/D5bQskrwV)\n- 🐛 **Issues:** [GitHub Issues](https://github.com/SocialAPIsHub/mcp-server/issues)\n- 📚 **Docs:** [docs.socialapis.io](https://docs.socialapis.io)\n\n---\n\n## 🗺️ Roadmap\n\n**Shipped:**\n\n- [x] Facebook API support — 31 tools (Pages, Groups, Posts, Search, Ads Library, Marketplace, Media)\n- [x] **Instagram support** — 16 tools (Profiles, Posts, Reels, Highlights, Discovery / Locations)\n- [x] MCP server implementation\n- [x] HTTP proxy server\n- [x] npm package published — [`@socialapis/mcp`](https://www.npmjs.com/package/@socialapis/mcp)\n- [x] **MCP Registry listing** — [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io)\n- [x] **Python SDK** — [`socialapis-sdk`](https://pypi.org/project/socialapis-sdk/) on PyPI (51 endpoints, MIT)\n- [x] **JavaScript / TypeScript SDK** — [`socialapis-sdk`](https://www.npmjs.com/package/socialapis-sdk) on npm (Node 18+, Bun, Deno, browsers)\n- [x] **Go SDK** — [github.com/SocialAPIsHub/socialapis-go](https://github.com/SocialAPIsHub/socialapis-go) (idiomatic, zero deps)\n\n**Upcoming:**\n\n- [ ] TikTok support\n- [ ] X (Twitter) support\n- [ ] LinkedIn support\n- [ ] YouTube support\n- [ ] Advanced analytics — server-side aggregation endpoints (engagement-over-time, brand comparisons) so multi-call patterns become a single tool call\n- [ ] Real-time webhooks — push notifications on new posts / engagement thresholds\n- [ ] LangChain integration\n\nPlatform priorities shift based on customer demand. The fastest way to push something up the queue is to email [support@socialapis.io](mailto:support@socialapis.io) or DM [@socialapis on Telegram](https://t.me/socialapis) with the use case.\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 Acknowledgments\n\n- Built with [Model Context Protocol](https://modelcontextprotocol.io)\n- Powered by [Anthropic Claude](https://anthropic.com)\n- Inspired by the AI agent community\n\n---\n\n## 🌟 Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=SocialAPIsHub/mcp-server&type=Date)](https://star-history.com/#SocialAPIsHub/mcp-server&Date)\n\n---\n\n<div align=\"center\">\n\n**Made with ❤️ by the SocialAPIs Team**\n\n[Website](https://socialapis.io) • [Twitter](https://twitter.com/socialapis) • [Discord](https://discord.gg/D5bQskrwV)\n\n[Python SDK](https://pypi.org/project/socialapis-sdk/) • [JS SDK](https://www.npmjs.com/package/socialapis-sdk) • [Go SDK](https://github.com/SocialAPIsHub/socialapis-go)\n\n</div>",
  "bytes": 14485,
  "sha": "f76d74094edb23ab1ae16e1cb7697568cab94b5b3be66a148ee59cd07e3fc105",
  "repo_slug": "socialapishub/mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_socialapishub_social_media_api_2019d733/readme"
}