socialapishub/socialapis
Facebook & Instagram data for AI agents: pages, posts, groups, Ads Library, Marketplace, profiles and reels. 12 read-only tools (50 actions) with structured output. Requires a SocialAPIs API key in the SOCIALAPIS_API_KEY environment variable (free tier at socialapis.io).
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[2.2.0] - 2026-10-27
Added
-
Live catalog. Tool prices, descriptions and parameters now follow the SocialAPIs API without a new release. The hosted server reads the public endpoint catalog (
https://auth.socialapis.io/api/public/endpoints) at startup and every 10 minutes and applies only what changed since the catalogsrc/tools.jswas written against (src/catalogBaseline.json): new prices, edited descriptions and parameter text, added / removed / now-required parameters, and "Currently unavailable." on a disabled endpoint's action. If the catalog can't be read, or a change can't be merged into a grouped tool, the last good definitions stay (the bundled ones at first).GET /healthgainscatalog: { source, version, fetchedAt, routes }. New env vars:SOCIALAPIS_CATALOG_URL,SOCIALAPIS_CATALOG_REFRESH_MS,SOCIALAPIS_LIVE_CATALOG=0(off). -
The npm client re-reads the tool list every 10 minutes (it used to keep the first one until restart), declares
tools.listChangedand sendsnotifications/tools/list_changedwhen the list changes. A failed fetch keeps the last list instead of an empty one. -
scripts/snapshot-catalog.mjsrewrites the baseline from the catalog URL or anendpoints.jsonfile (public fields only), and unit tests (npm run test:unit). -
Errors say what to do next. A failed call keeps the API's own JSON and adds a plain
hint: on a rate limit (HTTP 429) how long to wait (retryAfterSeconds, fromRetry-After) and not to retry at once; on missing credits how many the call needs and that retrying won't help; on a paused or expired plan, a bad key or a temporary server error, the next step. Nothing changes on successful calls.
Fixed
npm run test:unitruns on Node 22+ (node --testno longer expands a directory).
No tool or action names changed.
[2.1.1] - 2026-10-16
Fixed
- Instagram IDs.
instagram_get_user_id(instagram_profileaction=id) returns two IDs,user_id(long, e.g.17841401474538262) andpk(short, e.g.528817151), and the endpoints need different ones. Tool and parameter descriptions now say so: posts and reels take the longuser_id; highlights takes thepk(passed asuser_id). Before, every description said "the numeric user_id", so agents sent the wrong ID to highlights. Description text only; no tools, actions or schemas changed. - README roadmap counts: Facebook 7 tools / 37 actions, Instagram 5 tools / 13 actions (50 in total; the old split predated the album actions).
[2.1.0] - 2026-10-15
Added
- Facebook photo albums.
facebook_pageandfacebook_groupgetaction=albums(album_id, album_title, url, thumbnail_uri and item counts; pages takeprofile_idfromaction=id, groups takegroup_id; 8-16 per call) andaction=album_items(the photos and videos in an album, from a page or a group, with pagination). New REST endpoints:/facebook/pages/albums,/facebook/groups/albums,/facebook/albums/items. 1 credit per call. 50 actions (was 47), still 12 tools. - Calls tell the API they came through MCP. Each call the server forwards to the SocialAPIs API carries
x-socialapis-client: mcp, the transport (x-socialapis-mcp-via: npmorhosted) and the client name (x-socialapis-mcp-client, e.g. the MCP client's name/version or user agent). The API stores these on its request log so MCP usage can be seen per account. No arguments or keys are added.
Changed
- An endpoint can be listed under more than one tool (album items is an action on both
facebook_pageandfacebook_group); tool descriptions point to the action in the same tool.
[2.0.2] - 2026-10-08
Changed
- Shorter parameter descriptions. A parameter shared by several actions now has one plain description followed by
Required for: …/Optional for: …, instead of one sentence per action. Real per-action differences stay on one line, e.g.limit: "Results per call. posts: 3-9 (default 3) · videos: 6-12 (default 6)." Much easier to scan in tool forms (Glama, Smithery, MCP Inspector). - Line breaks for structure. Each action's
Inputs:sits on its own indented line under the action, andRequired for/Optional forsits on its own line under a parameter's description. Clients that keep line breaks (MCP Inspector, Claude) show the structure; clients that flatten text (Glama) show a space instead.
Added
- Call log. The server writes one JSON line per tool call, prefixed
[mcp]: transport (hosted or npm), client, tool, action, endpoint, HTTP status, credits charged, latency, and a short irreversible fingerprint of the API key. Hostedinitializerequests log the client name and version. Arguments and keys are never logged. - The npm client sends an
x-mcp-clientheader (MCP client name/version) so calls through it show which client is in use.
No tools, actions or schemas changed.
[2.0.1] - 2026-10-08
Changed
- Per-action inputs are spelled out. Grouped tools share one input list, so it wasn't clear which parameters each action takes. Each action in a tool description now lists all its inputs, marked required or optional (e.g.
action=comments: … Inputs: link (required), limit (optional), end_cursor (optional), include_reply_info (optional).). Each parameter description now names the actions that use it and whether it's required for each (e.g.link: details, id (required): Facebook post URL.).
No tools, actions or schemas changed. Only description text.
[2.0.0] - 2026-10-06
Changed
- 47 tools grouped into 12. Each tool covers one resource (
facebook_page,facebook_post,facebook_ads,instagram_profile, …) and takes anactionargument (details,posts,search, …). Every action from 1.x is still there, with the same parameters, endpoints and prices. Fewer tools fit under client tool limits (Cursor caps the total across servers) and are easier for agents to choose between. - A missing
actionor required parameter now returns a clear error before any credit is spent. /healthreportstools(12) andactions(47).
Compatibility
- The 47 1.x tool names still work when called directly (hosted
/mcp,/proxyand the npm client), so existing prompts and scripts keep running. They are no longer listed. - npm clients 1.2.x pick up the grouped tools automatically. 1.1.0 and older keep the old per-endpoint list from
GET /tools. - Breaking for configs that auto-approve or allow-list tools by name: add the new tool names.
[1.2.1] - 2026-10-06
Changed
- Clearer tool descriptions for all 47 tools. Each one now says what it returns, when to use it instead of a similar tool, and where its IDs come from. For example,
facebook_ads_keywordsfinds advertisers for a keyword, whilefacebook_ads_searchreturns the ads; post details vs. extended details; general Marketplace search vs. the vehicle and rental searches. Every description now states its price. - Clearer parameter descriptions for 33 parameters: Marketplace location and price filters, search queries, and IDs that come from another tool.
No tools were added, removed or renamed, and no input schemas changed. Existing configs and auto-approve lists keep working.
[1.2.0] - 2026-10-02
Added
- Tool annotations on all 47 tools:
readOnlyHint: true,destructiveHint: false,openWorldHint: true— every tool only reads public data, so clients can skip confirmation prompts. - Human-readable titles for every tool (e.g. "Facebook: Get Page Details").
- Structured output. Every tool declares an
outputSchemaand returnsstructuredContenton success:{ result, creditsCharged, creditsRemaining }.resultis the REST response unchanged; the credit fields are lifted out of itsmetablock so agents can track spend without parsing each endpoint's shape. The JSON text content is still returned for clients that ignore structured output. - Server identity in the MCP handshake: title, description, website and icon. Icon and title also added to
server.json.
Compatibility
GET /toolskeeps its previous shape (name, description, inputSchema). npm client 1.1.0 and older read it and don't return structured output, which clients require once a tool declaresoutputSchema. Client 1.2.0 requestsGET /tools?format=full. Upgrading is optional.
[1.1.0] - 2026-10-02
Added
- Hosted remote MCP endpoint at
https://mcp.socialapis.io/mcp(Streamable HTTP, stateless, JSON responses). Clients that support remote MCP servers can connect with a URL — no local install. - Authentication via
Authorization: Bearer <key>orx-api-token: <key>.tools/listworks without a key so directories and clients can show the tool catalog;tools/callreturns a clear error until a key is supplied. remotesentry inserver.jsonfor the official MCP Registry.
Changed
- Upgraded
@modelcontextprotocol/sdkfrom 0.5 to 1.31. The npm stdio client (npx @socialapis/mcp) is unchanged for users. - Backend calls now time out after 90s instead of hanging indefinitely.
- Descriptions (README,
package.json,server.json) now state exactly what is live: Facebook and Instagram. Removed TikTok and "multiple platforms" claims. facebook_get_page_detailsno longer mentions page likes — Facebook stopped exposing public page like counts.
Security
.dockerignorenow excludes MCP registry publisher token files so they can never be baked into an image.
[1.0.0] - 2025-01-17
Added
- Initial release of SocialAPIs MCP Server
- Support for 12 Facebook API tools
- MCP client (mcp-wrapper.js) for local execution
- HTTP proxy server for production deployment
- npm package published as @socialapis/mcp
- Comprehensive documentation and examples
- Support for Claude Desktop, Cursor, and VSCode
Tools Included
- Facebook page tools (ID, details, posts, reels)
- Facebook group tools (ID, details, posts)
- Facebook post tools (ID, details, attachments, comments)
- Facebook video tools (details)
Infrastructure
- Global edge network for low latency
- Automatic rate limiting
- Smart caching
- 99.9% uptime SLA
[Unreleased]
Planned
- TikTok support
- YouTube support
- Twitter/X support
- Real-time webhooks
- Advanced analytics
- Python SDK
- LangChain integration