SocialAPIs — Facebook & Instagram Data

official

Facebook & Instagram data for AI agents — pages, posts, groups, Ads Library, Marketplace, profiles and reels. 47 read-only tools, structured output. Free tier: 200 calls/month.

What can you do with SocialAPIs — Facebook & Instagram Data MCP?

  • Facebook page and group data — Pull page or group details, posts, videos, reels, and photo albums by link or ID.
  • Facebook post and comment lookup — Fetch post details, attachments, comments, and comment replies from a post link.
  • Meta Ads Library search — Search ads by keyword or advertiser, get advertiser page details, and list supported countries.
  • Instagram profile and post data — Retrieve profile details, posts, reels, highlights, and full post details by username or shortcode.
  • Instagram search and locations — Search by keyword for users, hashtags, and places, or list posts tagged at a location.
  • Facebook Marketplace search — Search listings, vehicles, and rentals with filters, and get listing or seller details.

Hosted MCP Server

npx add-mcp 'https://mcp.socialapis.io/mcp'

Installs into Claude Code, Codex, Cursor and more

Documentation

Give AI assistants direct access to public Facebook and Instagram data with the SocialAPIs Model Context Protocol (MCP) server.

The server exposes 12 read-only tools covering 50 actions: pages, posts, comments, groups, the Meta Ads Library, Marketplace, Instagram profiles, posts, reels and locations. Each tool covers one resource and takes an action argument. Every call returns structured output, including the credits charged and the credits remaining.

1. Get an API key

Sign up at socialapis.io and copy your key from the dashboard. The free plan includes 200 credits a month, no credit card needed.

2. Connect your client

There are two ways to connect.

Hosted endpoint (recommended)

Nothing to install. Point any client that supports remote MCP servers at:

https://mcp.socialapis.io/mcp

Send your key in a header:

Authorization: Bearer YOUR_API_KEY

x-api-token: YOUR_API_KEY also works. Never put the key in the URL.

Local server (npx)

For clients that only run local servers, such as Claude Desktop. Needs Node.js 18 or newer.

{
  "mcpServers": {
    "socialapis": {
      "command": "npx",
      "args": ["-y", "@socialapis/mcp"],
      "env": {
        "SOCIALAPIS_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Client setup

Claude Code

claude mcp add --transport http socialapis https://mcp.socialapis.io/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

VS Code

Add to .vscode/mcp.json. VS Code asks for the key when the server starts, so it isn't stored in the file:

{
  "servers": {
    "socialapis": {
      "type": "http",
      "url": "https://mcp.socialapis.io/mcp",
      "headers": {
        "Authorization": "Bearer ${input:socialapis-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "socialapis-key",
      "description": "SocialAPIs API key",
      "password": true
    }
  ]
}

Cline

In MCP Servers → Configure, add to cline_mcp_settings.json:

{
  "mcpServers": {
    "socialapis": {
      "type": "streamableHttp",
      "url": "https://mcp.socialapis.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "socialapis": {
      "serverUrl": "https://mcp.socialapis.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Available tools

Current version: 2.0.2. The server has 12 read-only tools. Each covers one resource and takes an action argument, plus that action's inputs:

ToolActions
facebook_pagedetails, id, posts, videos, reels, albums, album_items
facebook_groupdetails, id, posts, videos, albums, album_items
facebook_postdetails, details_extended, id, attachments, video, comments, comment_replies
facebook_searchpages, people, posts, videos, locations
facebook_adssearch, keywords, page_details, archive_details, countries
facebook_marketplacesearch, vehicles, rentals, listing, seller, categories, city_coordinates
facebook_media_downloaddownload
instagram_profiledetails, id, posts, reels, highlights, highlight_details
instagram_postdetails, id
instagram_reelsfeed, by_audio
instagram_searchsearch
instagram_locationposts, nearby

Example call:

{ "name": "facebook_post", "arguments": { "action": "comments", "link": "https://www.facebook.com/nike/posts/POST_ID", "limit": 20 } }

A missing action or required input returns an error before any credit is spent. Each tool's description in your client lists the same inputs, per action.

Upgrading from 1.x? The old per-endpoint tool names (such as facebook_get_page_details) still work when called directly, so existing scripts keep running. If your client auto-approves or allow-lists tools by name, add the new names above.

Inputs by action

Credits are per call unless noted. Pagination: pass the end_cursor from a response to get the next page.

facebook_page

Facebook pages: profile details, page ID, posts, videos, reels and photo albums.

ActionRequired inputsOptional inputsCredits
detailslinkexact_followers_count1 (5 with exact_followers_count=true)
idlink—1
postslinklimit, end_cursor, after_time, before_time, timezone1 per 3 posts returned (min 1)
videoslink or profile_idlimit, end_cursor1
reelslinkend_cursor1
albumsprofile_id (from id)limit (8-16), end_cursor1
album_itemsalbum_id (from albums)end_cursor1

facebook_group

Public Facebook groups: details, group ID, posts, videos and photo albums.

ActionRequired inputsOptional inputsCredits
detailslink—1
idlink—1
postslinklimit, end_cursor, after_time, before_time, timezone1 per 3 posts returned (min 1)
videoslinkend_cursor1
albumsgroup_id (from id)limit (8-16)1
album_itemsalbum_id (from albums)end_cursor1

facebook_post

Facebook posts, videos and comments: post details, attachments, comments and replies.

ActionRequired inputsOptional inputsCredits
detailslink—1
details_extendedlink—1
idlink—1
attachmentspost_id—5
videovideo_id—1
commentslinklimit, end_cursor, include_reply_info1
comment_repliescomment_feedback_id, expansion_token—1

facebook_search

Search Facebook by keyword: pages, people, posts, videos and locations.

ActionRequired inputsOptional inputsCredits
pagesquerylocation_uid, end_cursor1
peoplequerylocation_uid, end_cursor1
postsquerylocation_uid, start_time, end_time, recent_posts, end_cursor1
videosquerymost_recent, videos_live, fields, end_cursor1
locationsquery—1

facebook_ads

Meta Ads Library: search ads, find advertisers by keyword, advertiser page details, single ad details and supported countries.

ActionRequired inputsOptional inputsCredits
search—query, ad_page_id, country, activeStatus, after_time, before_time, sort_data, end_cursor1
keywordsquerycountry1
page_detailspage_id—1
archive_detailsad_archive_idpage_id, country, is_ad_non_political, is_ad_not_aaa_eligible1
countries——1

facebook_marketplace

Facebook Marketplace: search listings, vehicles and rentals, listing and seller details, categories and city coordinates.

ActionRequired inputsOptional inputsCredits
search—query, category_url, commerce_search_sort_by, commerce_search_and_rp_condition, filter_location_latitude, filter_location_longitude, filter_price_lower_bound, filter_price_upper_bound, filter_radius_km, posted_today, exact_match, limit, end_cursor1
vehicles—sort_by, filter_location_latitude, filter_location_longitude, filter_price_lower_bound, filter_price_upper_bound, filter_radius_km, is_c2c_listing_only, end_cursor1
rentals—sort_by, filter_location_latitude, filter_location_longitude, filter_price_lower_bound, filter_price_upper_bound, filter_radius_km, filter_bedrooms_min, filter_bedrooms_max, filter_bathrooms_min, filter_bathrooms_max, end_cursor1
listinglisting_id—1
sellerseller_id—1
categories——1
city_coordinatescitycountry, exactly_one1

facebook_media_download

Download Facebook media (images, videos, audio) from a URL.

ActionRequired inputsOptional inputsCredits
downloadurl—1

instagram_profile

Instagram profiles: details, user ID, posts, reels, highlights and highlight stories.

ActionRequired inputsOptional inputsCredits
detailsusernamelink1
id—link, username1
posts—username, user_id, end_cursor1
reelsuser_idend_cursor1
highlightsuser_id—1
highlight_detailshighlight_id—1

instagram_post

Instagram posts: full post details, or the shortcode from a post URL.

ActionRequired inputsOptional inputsCredits
detailsshortcode—1
idlink—1

instagram_reels

Instagram Reels: the trending feed, or reels that use a given audio track.

ActionRequired inputsOptional inputsCredits
feed—clips_media_id1
by_audioaudio_idmax_id1

instagram_search

Search Instagram by keyword for popular users, hashtags and places.

ActionRequired inputsOptional inputsCredits
searchkeywordend_cursor1

instagram_location

Instagram locations: posts tagged at a place, and nearby places.

ActionRequired inputsOptional inputsCredits
postslocation_idtab, end_cursor1
nearbylocation_id—1

Example prompts

"Get Nike's Facebook page details and summarize their last 10 posts."

"Compare follower counts for Adidas and Nike on Instagram."

"Find active ads in the Meta Ads Library that mention 'running shoes' in the US."

Troubleshooting

SymptomFix
Missing SocialAPIs API keyAdd the Authorization: Bearer <key> header (hosted) or SOCIALAPIS_API_KEY (npx).
HTTP 401 or 403 in a resultRe-copy the key from the dashboard.
Insufficient creditsUpgrade or top up at socialapis.io/pricing.
No tools listedRestart the client after editing its config, and check that https://mcp.socialapis.io/health answers (open it in a browser).

Where to find us

The server is listed on the official MCP Registry as io.github.SocialAPIsHub/social-media-api, and on Smithery, Glama, cursor.directory, LobeHub, mcp.so and mcpservers.org. See socialapis.io/integrations for links.

Source code: github.com/SocialAPIsHub/mcp-server. Questions: support@socialapis.io.