MCP Server
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:
| Tool | Actions |
|---|---|
facebook_page | details, id, posts, videos, reels, albums, album_items |
facebook_group | details, id, posts, videos, albums, album_items |
facebook_post | details, details_extended, id, attachments, video, comments, comment_replies |
facebook_search | pages, people, posts, videos, locations |
facebook_ads | search, keywords, page_details, archive_details, countries |
facebook_marketplace | search, vehicles, rentals, listing, seller, categories, city_coordinates |
facebook_media_download | download |
instagram_profile | details, id, posts, reels, highlights, highlight_details |
instagram_post | details, id |
instagram_reels | feed, by_audio |
instagram_search | search |
instagram_location | posts, 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.
| Action | Required inputs | Optional inputs | Credits |
|---|---|---|---|
details | link | exact_followers_count | 1 (5 with exact_followers_count=true) |
id | link | — | 1 |
posts | link | limit, end_cursor, after_time, before_time, timezone | 1 per 3 posts returned (min 1) |
videos | link or profile_id | limit, end_cursor | 1 |
reels | link | end_cursor | 1 |
albums | profile_id (from id) | limit (8-16), end_cursor | 1 |
album_items | album_id (from albums) | end_cursor | 1 |
facebook_group
Public Facebook groups: details, group ID, posts, videos and photo albums.
| Action | Required inputs | Optional inputs | Credits |
|---|---|---|---|
details | link | — | 1 |
id | link | — | 1 |
posts | link | limit, end_cursor, after_time, before_time, timezone | 1 per 3 posts returned (min 1) |
videos | link | end_cursor | 1 |
albums | group_id (from id) | limit (8-16) | 1 |
album_items | album_id (from albums) | end_cursor | 1 |
facebook_post
Facebook posts, videos and comments: post details, attachments, comments and replies.
| Action | Required inputs | Optional inputs | Credits |
|---|---|---|---|
details | link | — | 1 |
details_extended | link | — | 1 |
id | link | — | 1 |
attachments | post_id | — | 5 |
video | video_id | — | 1 |
comments | link | limit, end_cursor, include_reply_info | 1 |
comment_replies | comment_feedback_id, expansion_token | — | 1 |
facebook_search
Search Facebook by keyword: pages, people, posts, videos and locations.
| Action | Required inputs | Optional inputs | Credits |
|---|---|---|---|
pages | query | location_uid, end_cursor | 1 |
people | query | location_uid, end_cursor | 1 |
posts | query | location_uid, start_time, end_time, recent_posts, end_cursor | 1 |
videos | query | most_recent, videos_live, fields, end_cursor | 1 |
locations | query | — | 1 |
facebook_ads
Meta Ads Library: search ads, find advertisers by keyword, advertiser page details, single ad details and supported countries.
| Action | Required inputs | Optional inputs | Credits |
|---|---|---|---|
search | — | query, ad_page_id, country, activeStatus, after_time, before_time, sort_data, end_cursor | 1 |
keywords | query | country | 1 |
page_details | page_id | — | 1 |
archive_details | ad_archive_id | page_id, country, is_ad_non_political, is_ad_not_aaa_eligible | 1 |
countries | — | — | 1 |
facebook_marketplace
Facebook Marketplace: search listings, vehicles and rentals, listing and seller details, categories and city coordinates.
| Action | Required inputs | Optional inputs | Credits |
|---|---|---|---|
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_cursor | 1 |
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_cursor | 1 |
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_cursor | 1 |
listing | listing_id | — | 1 |
seller | seller_id | — | 1 |
categories | — | — | 1 |
city_coordinates | city | country, exactly_one | 1 |
facebook_media_download
Download Facebook media (images, videos, audio) from a URL.
| Action | Required inputs | Optional inputs | Credits |
|---|---|---|---|
download | url | — | 1 |
instagram_profile
Instagram profiles: details, user ID, posts, reels, highlights and highlight stories.
| Action | Required inputs | Optional inputs | Credits |
|---|---|---|---|
details | username | link | 1 |
id | — | link, username | 1 |
posts | — | username, user_id, end_cursor | 1 |
reels | user_id | end_cursor | 1 |
highlights | user_id | — | 1 |
highlight_details | highlight_id | — | 1 |
instagram_post
Instagram posts: full post details, or the shortcode from a post URL.
| Action | Required inputs | Optional inputs | Credits |
|---|---|---|---|
details | shortcode | — | 1 |
id | link | — | 1 |
instagram_reels
Instagram Reels: the trending feed, or reels that use a given audio track.
| Action | Required inputs | Optional inputs | Credits |
|---|---|---|---|
feed | — | clips_media_id | 1 |
by_audio | audio_id | max_id | 1 |
instagram_search
Search Instagram by keyword for popular users, hashtags and places.
| Action | Required inputs | Optional inputs | Credits |
|---|---|---|---|
search | keyword | end_cursor | 1 |
instagram_location
Instagram locations: posts tagged at a place, and nearby places.
| Action | Required inputs | Optional inputs | Credits |
|---|---|---|---|
posts | location_id | tab, end_cursor | 1 |
nearby | location_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
| Symptom | Fix |
|---|---|
Missing SocialAPIs API key | Add the Authorization: Bearer <key> header (hosted) or SOCIALAPIS_API_KEY (npx). |
| HTTP 401 or 403 in a result | Re-copy the key from the dashboard. |
Insufficient credits | Upgrade or top up at socialapis.io/pricing. |
| No tools listed | Restart 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.