Facebook API & MCP Server

What you can post

Facebook limits.

These are the limits the API enforces for Facebook, read straight from the code. Every post is checked against them before anything is sent.

Posts to Facebook Pages you manage. Personal profiles are not supported.

Text: 63,206 characters
Images: Up to 10 per post · JPEG, PNG, GIF · 9.5 MB each
Video: Up to 1 per post · MP4, MOV · 60 MB
Images and video together: Not in the same post
overrides.facebook.link: string · A URL to attach to a text post as a link preview. Not allowed with images or video.

Post with one request

Your first Facebook post.

Send the text and the account ID. Add an Idempotency-Key so a retried request never posts twice. The response lists each account with its own status and, once it’s live, the post’s URL.

curl https://socialhelper.app/api/v1/posts \
  -H "Authorization: Bearer $SOCIALHELPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
      "text": "We just shipped dark mode. Try it tonight 🌙",
      "accounts": [
          "ACCOUNT_ID"
      ]
  }'

const response = await fetch("https://socialhelper.app/api/v1/posts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SOCIALHELPER_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
      "text": "We just shipped dark mode. Try it tonight 🌙",
      "accounts": [
          "ACCOUNT_ID"
      ]
  }),
});

const { data: post } = await response.json();
console.log(post.status, post.targets);

import os, uuid, requests

response = requests.post(
    "https://socialhelper.app/api/v1/posts",
    headers={
        "Authorization": f"Bearer {os.environ['SOCIALHELPER_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "text": "We just shipped dark mode. Try it tonight 🌙",
        "accounts": ["ACCOUNT_ID"],
    },
)

post = response.json()["data"]
print(post["status"], post["targets"])

Tools

Facebook tools.

Call them with POST /api/v1/accounts/{id}/tools/{tool}, or let your agent use list_account_tools and run_account_tool over MCP. Results come back straight away.

list_posts

read-only

List the Page's most recent posts, newest first, with their text, permalink, creation time and reaction, comment and share counts.

limit integer: How many posts to return (1–50). default: 10
after string: The next_cursor from a previous call, to continue with older posts.

page_insights

read-only

Read Page Insights over time. Allowed metrics: page_media_view, page_total_media_view_unique, page_post_engagements, page_total_actions, page_views_total, page_follows, page_daily_follows_unique, page_daily_unfollows_unique, page_actions_post_reactions_total, page_video_views, page_video_views_organic, page_video_views_paid, page_video_complete_views_30s, page_video_view_time. page_follows, page_actions_post_reactions_total and page_video_view_time only support period "day". Meta needs the Page to have 100 or more followers, keeps two years of data and returns at most 90 days per request.

metrics array<string>: Metric names. Default: page_media_view, page_total_media_view_unique, page_post_engagements, page_daily_follows_unique, page_video_views.
period string: Aggregation of each value: one day, a rolling week, or a rolling 28 days. day | week | days_28 default: 'day'
since string: Start of the range, YYYY-MM-DD. Default: 28 days before until.
until string: End of the range, YYYY-MM-DD. Default: today (UTC).

post_insights

read-only

Read lifetime Insights for one of the Page's posts. Allowed metrics: post_media_view, post_total_media_view_unique, post_clicks, post_clicks_by_type, post_reactions_by_type_total, post_reactions_like_total, post_reactions_love_total, post_reactions_wow_total, post_reactions_haha_total, post_reactions_sorry_total, post_reactions_anger_total, post_video_views, post_video_views_organic, post_video_views_paid, post_video_avg_time_watched, post_video_view_time, post_video_complete_views_organic, post_video_complete_views_paid, post_video_length.

post_id* string: The post ID exactly as list_posts returns it ("{page-id}_{post-id}").
metrics array<string>: Metric names. Default: post_media_view, post_total_media_view_unique, post_clicks, post_reactions_by_type_total.

Connect

Connect Facebook once.

Open Accounts in the SocialHelper dashboard and choose Facebook. You sign in on Facebook’s own screen and approve access; SocialHelper stores the connection encrypted. You don’t need a Facebook developer app of your own.

1

Open Accounts

In the dashboard, choose Facebook.
2

Sign in on Facebook

Approve access on Facebook’s own screen.
3

Use the account ID

GET /api/v1/accounts lists the account with its ID, whether it can publish, and its tools.