Skip to main content

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.

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

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

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.