Skip to content

socialapishub/socialapis

v2.2.0MIT

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 catalog src/tools.js was 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 /health gains catalog: { 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.listChanged and sends notifications/tools/list_changed when the list changes. A failed fetch keeps the last list instead of an empty one.

  • scripts/snapshot-catalog.mjs rewrites the baseline from the catalog URL or an endpoints.json file (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, from Retry-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:unit runs on Node 22+ (node --test no longer expands a directory).

No tool or action names changed.

[2.1.1] - 2026-10-16

Fixed

  • Instagram IDs. instagram_get_user_id (instagram_profile action=id) returns two IDs, user_id (long, e.g. 17841401474538262) and pk (short, e.g. 528817151), and the endpoints need different ones. Tool and parameter descriptions now say so: posts and reels take the long user_id; highlights takes the pk (passed as user_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_page and facebook_group get action=albums (album_id, album_title, url, thumbnail_uri and item counts; pages take profile_id from action=id, groups take group_id; 8-16 per call) and action=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: npm or hosted) 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_page and facebook_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, and Required for / Optional for sits 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. Hosted initialize requests log the client name and version. Arguments and keys are never logged.
  • The npm client sends an x-mcp-client header (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 an action argument (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 action or required parameter now returns a clear error before any credit is spent.
  • /health reports tools (12) and actions (47).

Compatibility

  • The 47 1.x tool names still work when called directly (hosted /mcp, /proxy and 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_keywords finds advertisers for a keyword, while facebook_ads_search returns 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 outputSchema and returns structuredContent on success: { result, creditsCharged, creditsRemaining }. result is the REST response unchanged; the credit fields are lifted out of its meta block 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 /tools keeps 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 declares outputSchema. Client 1.2.0 requests GET /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> or x-api-token: <key>. tools/list works without a key so directories and clients can show the tool catalog; tools/call returns a clear error until a key is supplied.
  • remotes entry in server.json for the official MCP Registry.

Changed

  • Upgraded @modelcontextprotocol/sdk from 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_details no longer mentions page likes — Facebook stopped exposing public page like counts.

Security

  • .dockerignore now 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