{"id":49959299,"url":"https://github.com/oliverames/meta-mcp-server","last_synced_at":"2026-05-18T01:13:35.016Z","repository":{"id":345855661,"uuid":"1187649802","full_name":"oliverames/meta-mcp-server","owner":"oliverames","description":"The most comprehensive MCP server for Meta's business platform. 200+ tools covering Facebook Pages, Instagram, Threads, Ads Manager, Commerce, Conversions API, Audiences, Insights, and Ad Library.","archived":false,"fork":false,"pushed_at":"2026-04-21T18:49:04.000Z","size":582,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T19:44:51.908Z","etag":null,"topics":["ads-manager","ai","anthropic","automation","claude","conversions-api","facebook","facebook-ads","facebook-api","graph-api","instagram","instagram-api","llm","mcp","meta","meta-ads","model-context-protocol","social-media","threads","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/meta-mcp-server","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oliverames.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-21T01:19:26.000Z","updated_at":"2026-04-21T18:49:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oliverames/meta-mcp-server","commit_stats":null,"previous_names":["oliverames/meta-mcp-server"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/oliverames/meta-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliverames%2Fmeta-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliverames%2Fmeta-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliverames%2Fmeta-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliverames%2Fmeta-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oliverames","download_url":"https://codeload.github.com/oliverames/meta-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliverames%2Fmeta-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33161453,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T22:39:12.733Z","status":"ssl_error","status_checked_at":"2026-05-17T22:39:10.741Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ads-manager","ai","anthropic","automation","claude","conversions-api","facebook","facebook-ads","facebook-api","graph-api","instagram","instagram-api","llm","mcp","meta","meta-ads","model-context-protocol","social-media","threads","typescript"],"created_at":"2026-05-18T01:13:34.708Z","updated_at":"2026-05-18T01:13:35.008Z","avatar_url":"https://github.com/oliverames.png","language":"TypeScript","funding_links":["https://www.buymeacoffee.com/oliverames"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/icon.png\" width=\"80\" height=\"80\" alt=\"Meta\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eMeta MCP Server\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eConnect any AI assistant to Meta's entire business platform\u003c/strong\u003e\u003cbr\u003e\n  \u003csub\u003eFacebook Pages \u0026middot; Instagram \u0026middot; Threads \u0026middot; Ads Manager \u0026middot; Commerce \u0026middot; Conversions API \u0026middot; Insights\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ccode\u003e200 tools\u003c/code\u003e \u0026bull;\n  \u003ccode\u003e7 platforms\u003c/code\u003e \u0026bull;\n  \u003ccode\u003eGraph API v21.0\u003c/code\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@oliverames/meta-mcp-server\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@oliverames/meta-mcp-server?style=flat-square\u0026color=f5a542\" alt=\"npm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/oliverames/meta-mcp-server/releases/tag/v2.0.2\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/oliverames/meta-mcp-server?style=flat-square\u0026color=f5a542\u0026label=MCPB\" alt=\"MCPB release\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-f5a542?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.buymeacoffee.com/oliverames\"\u003e\u003cimg src=\"https://img.shields.io/badge/Buy_Me_a_Coffee-support-f5a542?style=flat-square\u0026logo=buy-me-a-coffee\u0026logoColor=white\" alt=\"Buy Me a Coffee\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#install-with-mcpb\"\u003eMCPB Download\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#what-you-can-do\"\u003eWhat You Can Do\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#complete-tool-reference\"\u003eAll 200 Tools\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#configuration\"\u003eConfiguration\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#architecture\"\u003eArchitecture\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Why This Exists\n\nSocial media management across Meta's platforms — Facebook Pages, Instagram, Threads, Ads Manager, Commerce — requires juggling multiple dashboards, each with its own API quirks and token flows. This server consolidates the entire Meta Graph API surface into a single MCP interface, so your AI assistant can publish content, analyze performance, manage ad campaigns, and moderate engagement across all platforms in one conversation.\n\nEvery tool returns actionable error messages — not cryptic API codes. Token expired? You get a regeneration link. Missing permission? You see exactly which one and where to grant it. This means less debugging and more doing.\n\n## Quick Start\n\n### Install with MCPB\n\nFor Claude Desktop and other MCPB-compatible clients, download the local bundle from the [v2.0.2 release](https://github.com/oliverames/meta-mcp-server/releases/tag/v2.0.2):\n\n[Download `meta-mcp-server-2.0.2.mcpb`](https://github.com/oliverames/meta-mcp-server/releases/download/v2.0.2/meta-mcp-server-2.0.2.mcpb)\n\nThe bundle includes the Meta favicon, production runtime dependencies, and setup prompts for Meta and optional Threads access tokens.\n\nAdd to your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"meta\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@oliverames/meta-mcp-server\"],\n      \"env\": {\n        \"META_ACCESS_TOKEN\": \"your_token_here\"\n      }\n    }\n  }\n}\n```\n\nThat's it. Your AI assistant now has access to 200 Meta tools.\n\n\u003e Need a token? Go to the [Graph API Explorer](https://developers.facebook.com/tools/explorer), select your app, and generate one. See [Configuration](#configuration) for details.\n\n### From Source\n\n```bash\ngit clone https://github.com/oliverames/meta-mcp-server.git\ncd meta-mcp-server\nnpm install \u0026\u0026 npm run build\n```\n\n---\n\n## What You Can Do\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### Publish everywhere\n\nPost to Facebook Pages (text, photo, video, Reels, Stories), Instagram (photos, reels, stories, carousels), and Threads (text, images, video, GIFs, links). Schedule content in advance or cross-post to multiple platforms in one call.\n\n```\n\u003e Post our holiday hours to the Facebook page\n\u003e Schedule an Instagram carousel for tomorrow at 9am\n\u003e Cross-post this photo to both Facebook and Instagram\n\u003e Publish a GIF to Threads with reply controls\n\u003e Create a Facebook Reel from this video\n\u003e Post a Story to our Facebook page\n\u003e Publish an Instagram reel with alt text for accessibility\n\u003e Share a link post on Threads with a quote\n```\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### Manage engagement\n\nRead and reply to comments across platforms, hide inappropriate content without deleting it, manage Instagram DMs and broadcast channels, and set up automated responses for when you're away.\n\n```\n\u003e Show me unanswered Instagram DMs\n\u003e Hide that offensive comment on our latest post\n\u003e Reply to the top 3 comments on yesterday's reel\n\u003e Set up an instant reply for new messages\n\u003e Set our away message to \"Back Monday at 9am\"\n\u003e Send a DM to that customer who reached out\n\u003e What comments did we get on last week's posts?\n\u003e Update our Messenger greeting text\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### Analyze performance\n\nGet insights at every level — page, post, account, campaign, ad set, and individual ad. Over 70 page metrics, comprehensive Reels analytics (including skip rate and crossposted views), and full ad performance with video completion rates, ROAS, and quality rankings. Generate charts for reports.\n\n```\n\u003e How did our Instagram perform this month?\n\u003e Show campaign spend broken down by age group\n\u003e What's the skip rate on our latest Reel?\n\u003e Generate a bar chart comparing this week vs last\n\u003e Get our Facebook page fan demographics\n\u003e What's our follower growth trend over 90 days?\n\u003e Show me post-level engagement for our top 5 posts\n\u003e Create a pie chart of spend by campaign\n```\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### Run ad campaigns\n\nFull campaign lifecycle — create, optimize, test, and automate. A/B testing with confidence levels, Advantage+ Shopping migration, interest/geo/demographic targeting search, reach estimates, automated rules, and comprehensive pixel management with server-side Conversions API.\n\n```\n\u003e Create an A/B test comparing these two ad sets\n\u003e Migrate this campaign to Advantage+ Shopping\n\u003e Send a purchase conversion event via CAPI\n\u003e What's the reach estimate for women 25-34 in NYC?\n\u003e List all active campaigns and their ROAS\n\u003e Create an automated rule: pause ads over $5 CPA\n\u003e Check if our pixel is firing correctly\n\u003e Upload this image for a new ad creative\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### Manage commerce\n\nFull product catalog management for Facebook and Instagram shops — add products, update inventory, organize collections, and manage availability. Everything a brand needs to run social commerce.\n\n```\n\u003e List all products in our catalog\n\u003e Add this new product at $29.99, in stock\n\u003e Mark the seasonal items as out of stock\n\u003e Show me our \"Summer Collection\" product set\n\u003e Update the description on our best-selling item\n\u003e How many products are in each catalog?\n\u003e Delete the discontinued product line\n\u003e What products are currently available?\n```\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### Go live and broadcast\n\nStart Facebook Live video broadcasts for product launches and events, publish Stories for time-sensitive content, and reach your audience directly through Instagram broadcast channels with polls, links, and messages.\n\n```\n\u003e Start a live video on our Facebook page\n\u003e Send a poll to our Instagram broadcast channel\n\u003e Schedule a live stream for Friday at 2pm\n\u003e Publish a story to Facebook with this photo\n\u003e End the live broadcast\n\u003e Send a product announcement to our broadcast channel\n\u003e What live videos have we done this month?\n\u003e What ads is our competitor running right now?\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### Research competitors\n\nSearch any advertiser's active ads through Meta's public Ad Library. See what creative, targeting, and spend your competitors are using — no account access needed. Look up any public Instagram business account's stats.\n\n```\n\u003e What ads is Nike running in the US right now?\n\u003e Search the Ad Library for \"sustainable fashion\" ads\n\u003e Look up @competitor on Instagram — followers and posts\n\u003e Show me all active ads by this page ID\n\u003e What platforms are they running ads on?\n\u003e How much is our competitor spending on ads?\n```\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### Stay in control\n\nDebug tokens, check permissions, monitor rate limits, verify pixel health, and manage your Business Manager assets. Every error tells you exactly what went wrong and how to fix it — never a cryptic failure.\n\n```\n\u003e Check my token status and permissions\n\u003e Am I close to Instagram's publishing limit?\n\u003e Run a health check on the Meta connection\n\u003e Is our pixel receiving events?\n\u003e List all ad accounts in our Business Manager\n\u003e Share this pixel with our agency's ad account\n\u003e What Threads rate limits do we have left?\n\u003e Debug why this API call is failing\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## Complete Tool Reference\n\n### Facebook Pages — 52 tools\n\nEverything a brand needs to manage their Facebook presence, messaging, and live broadcasts.\n\n| Tool | Description |\n|:---|:---|\n| `meta_list_pages` | List all Facebook Pages you manage *(call first — caches page tokens)* |\n| `meta_get_page` | Get detailed page info (category, followers, description, links) |\n| `meta_get_post` | Get a single post by ID |\n| `meta_create_post` | Create a text post on a page |\n| `meta_create_photo_post` | Create a photo post (URL or page photo ID) |\n| `meta_create_video_post` | Create a video post with optional title and description |\n| `meta_update_post` | Edit an existing post's message |\n| `meta_delete_post` | Delete a post |\n| `meta_get_posts` | Get a page's feed with pagination |\n| `meta_get_published_posts` | Get published posts only |\n| `meta_get_scheduled_posts` | Get scheduled (unpublished) posts |\n| `meta_get_promotable_posts` | Get posts eligible for ad promotion |\n| `meta_get_visitor_posts` | Get posts made by visitors on the page |\n| `meta_get_post_comments` | Get comments on a post with pagination |\n| `meta_reply_post_comment` | Reply to a comment as the page |\n| `meta_delete_comment` | Delete a comment |\n| `meta_hide_comment` | Hide or unhide a comment (non-destructive moderation) |\n| `meta_like_object` | Like or unlike a post or comment |\n| `meta_get_post_reactions` | Get reaction breakdown (like, love, haha, wow, sad, angry) |\n| `meta_get_page_insights` | Page analytics — 70+ metrics across impressions, engagement, fans, video |\n| `meta_get_post_insights` | Per-post analytics (impressions, engagement, clicks, reactions, video) |\n| `meta_get_page_conversations` | List page message conversations |\n| `meta_get_conversation_messages` | Get messages within a conversation |\n| `meta_send_page_message` | Send a message to a user (24-hour messaging window) |\n| `meta_update_page` | Update page details (about, description, website, hours, username, category, address) |\n| `meta_update_page_picture` | Update page profile picture from URL |\n| `meta_update_page_cover` | Update page cover photo from URL or existing photo |\n| `meta_create_event` | Create a page event |\n| `meta_get_page_events` | List events (upcoming, past, or canceled) |\n| `meta_get_page_albums` | List page photo albums |\n| `meta_get_page_photos` | Get photos (uploaded or tagged) |\n| `meta_get_page_videos` | List page videos |\n| `meta_get_page_tagged` | Get posts where the page is tagged |\n| `meta_get_page_fan_demographics` | Follower breakdown by age, gender, and country |\n| `meta_get_page_ratings` | Get page reviews and star ratings |\n| `meta_get_page_locations` | Location info for multi-location businesses |\n| `meta_get_page_cta` | Get the page's call-to-action button configuration |\n| `meta_get_page_tabs` | List page tabs and their configuration |\n| `meta_get_page_picture` | Get page profile picture URL |\n| `meta_get_blocked_users` | List blocked users |\n| `meta_block_user` | Block or unblock a user |\n| `meta_subscribe_page_webhooks` | Subscribe the page to webhook events |\n| `meta_publish_page_story` | Publish a Facebook Story (photo or video) |\n| `meta_publish_page_reel` | Publish a Facebook Reel |\n| `meta_cross_post` | Cross-post to Facebook + Instagram simultaneously |\n| `meta_create_live_video` | Start or schedule a live video broadcast |\n| `meta_get_live_videos` | List live videos on a page |\n| `meta_end_live_video` | End an active live broadcast |\n| `meta_get_page_automated_responses` | Get current auto-reply settings |\n| `meta_set_instant_reply` | Set the instant reply message |\n| `meta_set_away_message` | Set the away/out-of-office message |\n| `meta_set_greeting` | Set the Messenger greeting text |\n\n### Instagram — 37 tools\n\nFull Instagram Business API — publishing with scheduling, DMs, broadcast channels, engagement, discovery, and analytics.\n\n| Tool | Description |\n|:---|:---|\n| `meta_list_instagram_accounts` | List Instagram business accounts linked to your Facebook Pages |\n| `meta_get_instagram_media` | Get recent media for an Instagram account with pagination |\n| `meta_get_instagram_single_media` | Get a single media object by ID |\n| `meta_publish_instagram_photo` | Publish a photo with optional alt text and scheduling |\n| `meta_publish_instagram_reel` | Publish a reel with auto-polling and optional scheduling |\n| `meta_publish_instagram_story` | Publish a story (image or video with auto-polling) |\n| `meta_publish_instagram_carousel` | Publish a carousel (2–10 items, parallel processing, schedulable) |\n| `meta_publish_instagram_container` | Publish a pre-created media container |\n| `meta_check_instagram_container` | Check container processing status with actionable messages |\n| `meta_get_instagram_account_insights` | Account-level analytics with demographic breakdowns |\n| `meta_get_instagram_media_insights` | Per-post metrics including Reels skip rate, crossposted views |\n| `meta_get_instagram_comments` | Get comments on a media object |\n| `meta_get_instagram_comment_replies` | Get threaded replies to a comment |\n| `meta_reply_instagram_comment` | Reply to a comment |\n| `meta_delete_instagram_comment` | Delete a comment |\n| `meta_hide_instagram_comment` | Hide/unhide a comment (non-destructive moderation) |\n| `meta_search_instagram_catalog_products` | Search for products in an Instagram Shopping catalog by name |\n| `meta_search_instagram_hashtag` | Search hashtag top or recent media |\n| `meta_get_instagram_recent_hashtags` | Get your recently searched hashtags |\n| `meta_get_instagram_user` | Business discovery — look up any public business/creator by username |\n| `meta_get_instagram_stories` | Get currently active stories |\n| `meta_get_instagram_live_media` | Get live video media |\n| `meta_get_instagram_mentioned_media` | Get media where you're @mentioned |\n| `meta_get_instagram_media_children` | Get individual items in a carousel |\n| `meta_get_instagram_product_tags` | Get product tags on a media object |\n| `meta_delete_instagram_media` | Delete a media object |\n| `meta_toggle_instagram_comments` | Enable or disable comments on media |\n| `meta_check_instagram_publishing_limit` | Check rate limit status (100 posts per 24 hours) |\n| `meta_get_instagram_conversations` | List Instagram DM conversations |\n| `meta_get_instagram_messages` | Get messages in a DM conversation |\n| `meta_send_instagram_message` | Send a text DM |\n| `meta_send_instagram_media_message` | Send an image or link via DM |\n| `meta_get_instagram_available_catalogs` | List product catalogs available for Instagram Shopping on a professional account |\n| `meta_get_instagram_broadcast_channels` | List broadcast channels |\n| `meta_get_broadcast_channel_messages` | Get messages in a broadcast channel |\n| `meta_send_broadcast_channel_message` | Send a message to a broadcast channel |\n| `meta_create_broadcast_channel_poll` | Create a poll in a broadcast channel |\n\n### Ads Manager — 62 tools\n\nComplete ad campaign lifecycle — create, optimize, test, analyze, and automate. Includes Advantage+ migration, A/B testing, and comprehensive pixel management.\n\n| Tool | Description |\n|:---|:---|\n| `meta_list_ad_accounts` | List ad accounts you have access to |\n| `meta_get_ad_account` | Get ad account details (status, currency, spend cap, balance) |\n| `meta_list_campaigns` | List campaigns with status filtering and pagination |\n| `meta_get_campaign` | Get a single campaign's full details |\n| `meta_create_campaign` | Create a campaign (supports Advantage+ Shopping for OUTCOME_SALES) |\n| `meta_update_campaign` | Update campaign name, status, budget, or migrate to Advantage+ |\n| `meta_delete_campaign` | Delete a campaign |\n| `meta_migrate_campaign_to_advantage_plus` | Migrate a campaign to Advantage+ Shopping (keeps campaign ID) |\n| `meta_list_adsets` | List ad sets with filtering |\n| `meta_get_adset` | Get a single ad set's targeting and budget details |\n| `meta_create_adset` | Create an ad set with targeting, budget, and placement_soft_opt_out |\n| `meta_update_adset` | Update ad set targeting, budget, or placement_soft_opt_out |\n| `meta_delete_adset` | Delete an ad set |\n| `meta_list_ads` | List ads with status filtering |\n| `meta_get_ad` | Get a single ad's details |\n| `meta_create_ad` | Create an ad linking a creative to an ad set |\n| `meta_update_ad` | Update ad name, status, or creative |\n| `meta_delete_ad` | Delete an ad |\n| `meta_list_ad_creatives` | List ad creatives |\n| `meta_get_ad_creative` | Get a single creative's details |\n| `meta_create_ad_creative` | Create an ad creative with text, image, and link |\n| `meta_get_ad_preview` | Preview how an ad will appear in different placements |\n| `meta_get_ad_rule` | Get details for a specific automated ad rule |\n| `meta_get_ad_account_users` | List users with access to the ad account |\n| `meta_upload_ad_image` | Upload an image for use in ad creatives |\n| `meta_list_ad_images` | List previously uploaded ad images |\n| `meta_upload_ad_video` | Upload a video for use in ad creatives |\n| `meta_list_ad_videos` | List previously uploaded ad videos |\n| `meta_search_targeting_interests` | Search for interest-based targeting options |\n| `meta_search_targeting_geolocations` | Search for location-based targeting (countries, cities, zips) |\n| `meta_search_targeting_demographics` | Search for demographic targeting options |\n| `meta_browse_targeting_categories` | Browse all available targeting categories |\n| `meta_get_reach_estimate` | Estimate potential audience size for a targeting spec |\n| `meta_get_delivery_estimate` | Estimate ad delivery for a given budget and targeting |\n| `meta_get_leadgen_leads` | Get submitted leads from a lead generation form |\n| `meta_get_minimum_budgets` | Get minimum daily and lifetime budgets for an ad account by currency and bid strategy |\n| `meta_list_leadgen_forms` | List lead generation forms for a Facebook Page |\n| `meta_list_offline_event_sets` | List offline conversion event sets for an ad account |\n| `meta_list_pixels` | List Meta Pixels for conversion tracking |\n| `meta_create_pixel` | Create a new pixel |\n| `meta_get_pixel` | Get pixel details (name, cookie status, matching fields) |\n| `meta_get_pixel_stats` | Get event volume stats over time (verify pixel is firing) |\n| `meta_update_pixel` | Update pixel settings (name, cookies, matching, data use) |\n| `meta_delete_pixel` | Delete a pixel |\n| `meta_share_pixel` | Share pixel access with another ad account |\n| `meta_get_pixel_events` | Get recent test events for debugging |\n| `meta_list_custom_conversions` | List custom conversion events |\n| `meta_create_custom_conversion` | Create a custom conversion from pixel events |\n| `meta_list_saved_audiences` | List saved audiences |\n| `meta_create_saved_audience` | Create a reusable saved audience |\n| `meta_delete_saved_audience` | Delete a saved audience |\n| `meta_list_ad_rules` | List automated ad rules |\n| `meta_create_ad_rule` | Create an automated rule (e.g., pause ads over $5 CPA) |\n| `meta_delete_ad_rule` | Delete an automated rule |\n| `meta_list_ad_labels` | List ad labels for organization |\n| `meta_create_ad_label` | Create an ad label |\n| `meta_get_ad_account_activity` | Get the ad account's activity log |\n| `meta_list_business_assets` | List pages, ad accounts, IG accounts, and pixels across Business Manager |\n| `meta_create_ad_study` | Create an A/B test to compare campaigns or ad sets |\n| `meta_get_ad_studies` | List A/B tests for an ad account |\n| `meta_get_ad_study_results` | Get A/B test results with winner and confidence level |\n| `meta_send_offline_event` | Send an offline conversion event for in-store purchases, phone orders, or other offline conversions |\n\n### Threads — 22 tools\n\nFull Threads API — publishing with GIFs, reply controls, location tagging, and analytics.\n\n| Tool | Description |\n|:---|:---|\n| `threads_get_profile` | Get your Threads profile info |\n| `threads_get_posts` | Get your recent posts with pagination |\n| `threads_get_post` | Get a single post by ID (includes reply_audience) |\n| `threads_search` | Search your posts by keyword |\n| `threads_publish_text` | Publish a text post (with reply control and location) |\n| `threads_publish_image` | Publish an image post (with reply control and location) |\n| `threads_publish_video` | Publish a video post with auto-polling (with reply control and location) |\n| `threads_publish_carousel` | Publish a carousel (parallel creation, with reply control) |\n| `threads_publish_link` | Publish a post with a link attachment (with reply control) |\n| `threads_publish_gif` | Publish a GIF post via GIPHY URL |\n| `threads_delete_post` | Delete a post |\n| `threads_get_replies` | Get replies to a post |\n| `threads_get_conversation` | Get the full conversation tree for a post |\n| `threads_get_followers` | List followers of the authenticated Threads user |\n| `threads_get_following` | List accounts the authenticated Threads user is following |\n| `threads_get_mentions` | Get posts that @mention you |\n| `threads_get_media_children` | Get individual items in a carousel post |\n| `threads_hide_reply` | Hide or unhide a reply |\n| `threads_repost` | Repost a Threads post |\n| `threads_get_post_insights` | Get metrics for a specific post (views, likes, replies, etc.) |\n| `threads_get_user_insights` | Get account-level metrics with demographic breakdowns |\n| `threads_check_rate_limits` | Check your current publishing rate limit status |\n\n### Commerce — 10 tools\n\nProduct catalog management for Facebook and Instagram shops.\n\n| Tool | Description |\n|:---|:---|\n| `meta_list_product_catalogs` | List product catalogs for a business |\n| `meta_get_product_catalog` | Get catalog details and product count |\n| `meta_list_products` | List products in a catalog with filtering |\n| `meta_get_product` | Get a single product's full details |\n| `meta_create_product` | Add a product to a catalog |\n| `meta_create_product_feed` | Create a product feed to automatically sync products from a URL |\n| `meta_update_product` | Update product details (name, price, availability, etc.) |\n| `meta_delete_product` | Delete a product from a catalog |\n| `meta_list_product_feeds` | List product feeds for a catalog |\n| `meta_list_product_sets` | List product sets (subgroups) in a catalog |\n\n### Conversions API — 2 tools\n\nServer-side event tracking for conversion optimization.\n\n| Tool | Description |\n|:---|:---|\n| `meta_send_conversion_event` | Send a server-side conversion event (Purchase, Lead, etc.) to a pixel |\n| `meta_test_conversion_events` | Test CAPI setup without affecting production data |\n\n### Audiences — 5 tools\n\nCustom and lookalike audience management for ad targeting.\n\n| Tool | Description |\n|:---|:---|\n| `meta_list_custom_audiences` | List custom audiences in an ad account |\n| `meta_get_custom_audience` | Get audience details (size, delivery status) |\n| `meta_create_custom_audience` | Create a custom audience |\n| `meta_create_lookalike_audience` | Create a lookalike audience from a source audience |\n| `meta_delete_custom_audience` | Delete a custom audience |\n\n### Insights — 4 tools\n\nPerformance analytics across the ad hierarchy with 37 metrics, 15 date presets, and 8 breakdown dimensions.\n\n| Tool | Description |\n|:---|:---|\n| `meta_get_account_insights` | Ad account performance — spend, impressions, reach, clicks, CTR, CPM, CPC, conversions, ROAS, video completion, quality rankings |\n| `meta_get_campaign_insights` | Per-campaign performance with the same comprehensive metrics |\n| `meta_get_adset_insights` | Per-ad-set performance |\n| `meta_get_ad_insights` | Per-ad performance |\n\n### Charts — 2 tools\n\nGenerate visual charts from data for reports and presentations.\n\n| Tool | Description |\n|:---|:---|\n| `meta_generate_chart` | Create bar, line, pie, doughnut, radar charts as PNG images |\n| `meta_generate_comparison_chart` | Generate side-by-side comparison charts (A/B, period-over-period) |\n\n### Ad Library \u0026 Utility — 4 tools\n\n| Tool | Description |\n|:---|:---|\n| `meta_search_ad_library` | Search any advertiser's active ads — public transparency API |\n| `meta_debug_token` | Inspect your token: type, validity, expiry, permissions, associated app and user |\n| `meta_health_check` | Check server health: token status, cached tokens, API connectivity |\n| `meta_search_places` | Search Facebook Places (locations) by name or coordinates for post tagging |\n\n---\n\n## Configuration\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `META_ACCESS_TOKEN` | Yes | None | Long-lived Meta Graph API token for Facebook Pages, Instagram, Ads Manager, Commerce, Conversions API, Audiences, Insights, and utility tools. |\n| `THREADS_ACCESS_TOKEN` | No | None | Threads API token. Required only for Threads publishing, replies, and insights tools. |\n\n### 1. Create a Meta App\n\nGo to [developers.facebook.com](https://developers.facebook.com) → **My Apps** → **Create App** → choose **Business** type. Add **Facebook Login**, **Pages API**, **Instagram Graph API**, and **Marketing API**.\n\n### 2. Generate Tokens\n\nGet a token from the [Graph API Explorer](https://developers.facebook.com/tools/explorer), then exchange it for a long-lived token (60 days):\n\n```bash\ncurl \"https://graph.facebook.com/oauth/access_token?\\\ngrant_type=fb_exchange_token\u0026\\\nclient_id=YOUR_APP_ID\u0026\\\nclient_secret=YOUR_APP_SECRET\u0026\\\nfb_exchange_token=SHORT_LIVED_TOKEN\"\n```\n\n\u003e **For permanent access**, create a System User token in Business Manager → System Users.\n\n**Threads** uses a separate token via `graph.threads.net` OAuth — see [Threads API docs](https://developers.facebook.com/docs/threads/get-started).\n\n### 1Password Integration\n\nIf `META_ACCESS_TOKEN` or `THREADS_ACCESS_TOKEN` are not set in the environment, the server automatically attempts to resolve them from [1Password CLI](https://developer.1password.com/docs/cli/):\n\n```\nop://Development/Meta Access Token/credential\nop://Development/Threads Access Token/credential\n```\n\nThis means you can skip setting env vars entirely if you have `op` installed and a service account or session active. The fallback adds ~1-2s to startup per token and is silently skipped if 1Password is unavailable.\n\n### 3. Grant Permissions\n\n| Permission | Required for |\n|:---|:---|\n| `pages_show_list` | Listing pages |\n| `pages_read_engagement` | Page insights, reactions |\n| `pages_manage_posts` | Creating, editing, deleting posts |\n| `pages_manage_metadata` | Page settings, webhooks, profile picture, cover photo |\n| `pages_read_user_content` | Tagged posts, visitor posts, ratings |\n| `pages_messaging` | Reading and sending messages, automated responses |\n| `instagram_basic` | Instagram account info |\n| `instagram_content_publish` | Publishing photos, reels, stories, carousels |\n| `instagram_manage_insights` | Instagram analytics |\n| `instagram_manage_comments` | Comment management |\n| `instagram_manage_messages` | Instagram DMs |\n| `ads_read` | Reading campaigns, ad sets, ads, insights |\n| `ads_management` | Creating and managing ads, A/B tests |\n| `business_management` | Business Manager assets, product catalogs |\n| `catalog_management` | Product catalog CRUD |\n| `threads_basic` | Threads profile and posts |\n| `threads_content_publish` | Publishing to Threads |\n| `threads_manage_insights` | Threads analytics |\n| `threads_manage_replies` | Managing Threads replies |\n\n### 4. Connect to Your MCP Client\n\n**Claude Code** — add to `~/.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"meta\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/meta-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"META_ACCESS_TOKEN\": \"your_long_lived_token\",\n        \"THREADS_ACCESS_TOKEN\": \"your_threads_token\"\n      }\n    }\n  }\n}\n```\n\nWorks with any MCP client that supports **stdio transport**. `THREADS_ACCESS_TOKEN` is optional — only needed for Threads tools.\n\n---\n\n## How It Works\n\nThe server starts without any tokens configured — no crashes, no \"failed\" status in MCP settings. When you call a tool without proper auth, you get a clear setup message.\n\n**First call should always be `meta_list_pages`** — this caches the page-scoped access tokens required for all Page and Instagram operations.\n\n### Error Handling\n\nEvery error message tells you what went wrong, why, and how to fix it:\n\n| What happened | What you see |\n|:---|:---|\n| No token set | Step-by-step setup instructions with link to Graph Explorer |\n| Token expired (code 190) | Direct link to regenerate at developers.facebook.com |\n| Missing permission (code 10/200) | Names the exact permission needed and where to grant it |\n| Rate limited (429) | Tells you to wait, links to Meta's rate limit docs |\n| Page token missing | Reminds you to call `meta_list_pages` first |\n| Network unreachable | \"Cannot reach graph.facebook.com — check your connection\" |\n\n### Token Refresh\n\nLong-lived tokens expire after 60 days. Use `meta_debug_token` to check expiry, then refresh:\n\n```bash\ncurl \"https://graph.facebook.com/oauth/access_token?\\\ngrant_type=fb_exchange_token\u0026\\\nclient_id=APP_ID\u0026client_secret=APP_SECRET\u0026\\\nfb_exchange_token=CURRENT_TOKEN\"\n```\n\n\u003e For permanent tokens, create a System User in Business Manager → System Users.\n\n---\n\n## Architecture\n\n```\nsrc/\n├── index.ts              Server entry point (stdio transport)\n├── constants.ts          API versions, base URLs, field constants\n├── types.ts              TypeScript interfaces for Meta entities\n├── services/\n│   ├── api.ts            MetaApiClient — dual Graph + Threads API\n│   └── utils.ts          Error handling, formatting, shared schemas\n└── tools/\n    ├── pages.ts          52 Facebook Page tools\n    ├── instagram.ts      37 Instagram tools\n    ├── ads.ts            62 Ads Manager tools\n    ├── threads.ts        22 Threads tools\n    ├── commerce.ts       10 Commerce/Catalog tools\n    ├── conversions.ts     2 Conversions API tools\n    ├── audiences.ts       5 Audience tools\n    ├── insights.ts        4 Insight tools\n    ├── charts.ts          2 Chart generation tools\n    ├── ad_library.ts      1 Ad Library tool\n    └── utility.ts         3 Utility tools\n```\n\n### Key Design Decisions\n\n- **Dual API client** — Handles both `graph.facebook.com/v21.0` and `graph.threads.net/v1.0` with separate base URLs and tokens\n- **Page token caching** — `meta_list_pages` caches page-scoped tokens; subsequent tools look them up by page ID\n- **Two-step container publishing** — Instagram and Threads require container → publish flow; the server handles this automatically with video processing polling\n- **Parallel carousel processing** — All carousel items created concurrently via `Promise.allSettled`; partial failures report which items succeeded\n- **Zod strict schemas** — Every tool uses strict Zod schemas for type-safe parameter validation\n- **Dual output format** — Every read tool supports `response_format: \"markdown\"` or `\"json\"`\n- **Graceful auth** — Server starts without tokens, returns setup instructions on first tool call instead of crashing\n- **Chart generation** — QuickChart integration for rendering data as PNG images for reports\n\n---\n\n## API Coverage\n\nTargets **Meta Graph API v21.0** and **Threads API v1.0**.\n\n| API | Status |\n|:---|:---|\n| Facebook Pages API | **Comprehensive** — posts, comments, messaging, insights, events, media, Stories, Reels, Live Video, automated responses |\n| Instagram Graph API | **Comprehensive** — publishing, scheduling, comments, DMs, broadcast channels, hashtags, business discovery, insights |\n| Marketing API | **Comprehensive** — campaigns, ad sets, ads, creatives, targeting, audiences, pixels, CAPI, A/B testing, Advantage+ |\n| Threads API | **Comprehensive** — publishing (text, image, video, GIF, carousel, link), reply controls, location, insights |\n| Commerce API | **Supported** — product catalog CRUD, product sets |\n| Conversions API | **Supported** — server-side event tracking with test mode |\n| Ad Library API | **Supported** — public transparency search |\n| WhatsApp Business API | Not covered — separate infrastructure and token flow |\n\n---\n\n## Development\n\nUse the same commands for local development and contribution checks:\n\n```bash\nnpm install\nnpm test            # 52 tests\nnpm run build       # TypeScript compilation\nnpm run test:watch  # Development mode\n```\n\nDevelopment conventions: Zod `.strict()` schemas, `response_format` parameter on read tools, and `errorResult()` for tool errors with `isError: true`.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eNot affiliated with or endorsed by Meta Platforms, Inc.\u003c/sub\u003e\n\u003c/p\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.buymeacoffee.com/oliverames\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Buy_Me_a_Coffee-support-f5a542?style=for-the-badge\u0026logo=buy-me-a-coffee\u0026logoColor=white\" alt=\"Buy Me a Coffee\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003e\n    Built by \u003ca href=\"https://ames.consulting\"\u003eOliver Ames\u003c/a\u003e in Vermont\n    \u0026bull; \u003ca href=\"https://github.com/oliverames\"\u003eGitHub\u003c/a\u003e\n    \u0026bull; \u003ca href=\"https://linkedin.com/in/oliverames\"\u003eLinkedIn\u003c/a\u003e\n    \u0026bull; \u003ca href=\"https://bsky.app/profile/oliverames.bsky.social\"\u003eBluesky\u003c/a\u003e\n  \u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foliverames%2Fmeta-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foliverames%2Fmeta-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foliverames%2Fmeta-mcp-server/lists"}