Why This Exists
Social 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.
Every 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.
Quick Start
Install with MCPB
For Claude Desktop and other MCPB-compatible clients, download the local bundle from the v2.0.2 release:
Download meta-mcp-server-2.0.2.mcpb
The bundle includes the Meta favicon, production runtime dependencies, and setup prompts for Meta and optional Threads access tokens.
Add to your MCP client config:
{
"mcpServers": {
"meta": {
"command": "npx",
"args": ["-y", "@oliverames/meta-mcp-server"],
"env": {
"META_ACCESS_TOKEN": "your_token_here"
}
}
}
}
That's it. Your AI assistant now has access to 199 Meta tools.
Need a token? Go to the Graph API Explorer, select your app, and generate one. See Configuration for details.
From Source
git clone https://github.com/oliverames/meta-mcp-server.git
cd meta-mcp-server
npm install && npm run build
What You Can Do
Publish everywhere
Post 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.
> Post our holiday hours to the Facebook page
> Schedule an Instagram carousel for tomorrow at 9am
> Cross-post this photo to both Facebook and Instagram
> Publish a GIF to Threads with reply controls
> Create a Facebook Reel from this video
> Post a Story to our Facebook page
> Publish an Instagram reel with alt text for accessibility
> Share a link post on Threads with a quote
Manage engagement
Read 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.
> Show me unanswered Instagram DMs
> Hide that offensive comment on our latest post
> Reply to the top 3 comments on yesterday's reel
> Set up an instant reply for new messages
> Set our away message to "Back Monday at 9am"
> Send a DM to that customer who reached out
> What comments did we get on last week's posts?
> Update our Messenger greeting text
Analyze performance
Get 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.
> How did our Instagram perform this month?
> Show campaign spend broken down by age group
> What's the skip rate on our latest Reel?
> Generate a bar chart comparing this week vs last
> Get our Facebook page fan demographics
> What's our follower growth trend over 90 days?
> Show me post-level engagement for our top 5 posts
> Create a pie chart of spend by campaign
Run ad campaigns
Full 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.
> Create an A/B test comparing these two ad sets
> Migrate this campaign to Advantage+ Shopping
> Send a purchase conversion event via CAPI
> What's the reach estimate for women 25-34 in NYC?
> List all active campaigns and their ROAS
> Create an automated rule: pause ads over $5 CPA
> Check if our pixel is firing correctly
> Upload this image for a new ad creative
Manage commerce
Full 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.
> List all products in our catalog
> Add this new product at $29.99, in stock
> Mark the seasonal items as out of stock
> Show me our "Summer Collection" product set
> Update the description on our best-selling item
> How many products are in each catalog?
> Delete the discontinued product line
> What products are currently available?
Go live and broadcast
Start 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.
> Start a live video on our Facebook page
> Send a poll to our Instagram broadcast channel
> Schedule a live stream for Friday at 2pm
> Publish a story to Facebook with this photo
> End the live broadcast
> Send a product announcement to our broadcast channel
> What live videos have we done this month?
> What ads is our competitor running right now?
Research competitors
Search 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.
> What ads is Nike running in the US right now?
> Search the Ad Library for "sustainable fashion" ads
> Look up @competitor on Instagram — followers and posts
> Show me all active ads by this page ID
> What platforms are they running ads on?
> How much is our competitor spending on ads?
Stay in control
Debug 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.
> Check my token status and permissions
> Am I close to Instagram's publishing limit?
> Run a health check on the Meta connection
> Is our pixel receiving events?
> List all ad accounts in our Business Manager
> Share this pixel with our agency's ad account
> What Threads rate limits do we have left?
> Debug why this API call is failing
Complete Tool Reference
Facebook Pages — 52 tools
Everything a brand needs to manage their Facebook presence, messaging, and live broadcasts.
Instagram — 37 tools
Full Instagram Business API — publishing with scheduling, DMs, broadcast channels, engagement, discovery, and analytics.
Ads Manager — 62 tools
Complete ad campaign lifecycle — create, optimize, test, analyze, and automate. Includes Advantage+ migration, A/B testing, and comprehensive pixel management.
Threads — 22 tools
Full Threads API — publishing with GIFs, reply controls, location tagging, and analytics.
Commerce — 10 tools
Product catalog management for Facebook and Instagram shops.
Conversions API — 2 tools
Server-side event tracking for conversion optimization.
Audiences — 5 tools
Custom and lookalike audience management for ad targeting.
Insights — 4 tools
Performance analytics across the ad hierarchy with 37 metrics, 15 date presets, and 8 breakdown dimensions.
Charts — 2 tools
Generate visual charts from data for reports and presentations.
Ad Library & Utility — 4 tools
Configuration
1. Create a Meta App
Go to developers.facebook.com → My Apps → Create App → choose Business type. Add Facebook Login, Pages API, Instagram Graph API, and Marketing API.
2. Generate Tokens
Get a token from the Graph API Explorer, then exchange it for a long-lived token (60 days):
curl "https://graph.facebook.com/oauth/access_token?\
grant_type=fb_exchange_token&\
client_id=YOUR_APP_ID&\
client_secret=YOUR_APP_SECRET&\
fb_exchange_token=SHORT_LIVED_TOKEN"
For permanent access, create a System User token in Business Manager → System Users.
Threads uses a separate token via graph.threads.net OAuth — see Threads API docs.
Error reporting
Error reporting is off by default. If you set SENTRY_DSN, unexpected tool failures (code errors, Graph API 5xx responses, network failures, and timeouts) and fatal errors are sent to that Sentry project. Without it, @sentry/node is never loaded. Reporting needs Node 20.19 or newer and is skipped quietly on older runtimes.
Each report carries only the error type, a fixed message, stack frames with package-relative paths, the tool name, and the HTTP status of a failed Graph API response. Access tokens, post and message content, comments, ad and audience data, customer data, tool arguments, error messages, Graph API responses, breadcrumbs, user data, and request data are removed before anything is sent. Missing tokens and Graph API 4xx answers are not reported.
1Password Integration
If META_ACCESS_TOKEN or THREADS_ACCESS_TOKEN are not set in the environment, the server automatically attempts to resolve them from 1Password CLI:
op://Development/Meta Access Token/credential
op://Development/Threads Access Token/credential
This 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.
3. Grant Permissions
4. Connect to Your MCP Client
Claude Code — add to ~/.claude/settings.json:
{
"mcpServers": {
"meta": {
"command": "node",
"args": ["/absolute/path/to/meta-mcp-server/dist/index.js"],
"env": {
"META_ACCESS_TOKEN": "your_long_lived_token",
"THREADS_ACCESS_TOKEN": "your_threads_token"
}
}
}
}
Works with any MCP client that supports stdio transport. THREADS_ACCESS_TOKEN is optional — only needed for Threads tools.
How It Works
The 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.
First call should always be meta_list_pages — this caches the page-scoped access tokens required for all Page and Instagram operations.
Error Handling
Every error message tells you what went wrong, why, and how to fix it:
Token Refresh
Long-lived tokens expire after 60 days. Use meta_debug_token to check expiry, then refresh:
curl "https://graph.facebook.com/oauth/access_token?\
grant_type=fb_exchange_token&\
client_id=APP_ID&client_secret=APP_SECRET&\
fb_exchange_token=CURRENT_TOKEN"
For permanent tokens, create a System User in Business Manager → System Users.
Architecture
src/
├── index.ts Server entry point (stdio transport)
├── constants.ts API versions, base URLs, field constants
├── types.ts TypeScript interfaces for Meta entities
├── services/
│ ├── api.ts MetaApiClient — dual Graph + Threads API
│ └── utils.ts Error handling, formatting, shared schemas
└── tools/
├── pages.ts 52 Facebook Page tools
├── instagram.ts 37 Instagram tools
├── ads.ts 62 Ads Manager tools
├── threads.ts 22 Threads tools
├── commerce.ts 10 Commerce/Catalog tools
├── conversions.ts 2 Conversions API tools
├── audiences.ts 5 Audience tools
├── insights.ts 4 Insight tools
├── charts.ts 2 Chart generation tools
├── ad_library.ts 1 Ad Library tool
└── utility.ts 3 Utility tools
Key Design Decisions
- Dual API client — Handles both
graph.facebook.com/v21.0andgraph.threads.net/v1.0with separate base URLs and tokens - Page token caching —
meta_list_pagescaches page-scoped tokens; subsequent tools look them up by page ID - Two-step container publishing — Instagram and Threads require container → publish flow; the server handles this automatically with video processing polling
- Parallel carousel processing — All carousel items created concurrently via
Promise.allSettled; partial failures report which items succeeded - Zod strict schemas — Every tool uses strict Zod schemas for type-safe parameter validation
- Dual output format — Every read tool supports
response_format: "markdown"or"json" - Graceful auth — Server starts without tokens, returns setup instructions on first tool call instead of crashing
- Chart generation — QuickChart integration for rendering data as PNG images for reports
API Coverage
Targets Meta Graph API v21.0 and Threads API v1.0.
Development
Use the same commands for local development and contribution checks:
npm install
npm test # 52 tests
npm run build # TypeScript compilation
npm run test:watch # Development mode
Development conventions: Zod .strict() schemas, response_format parameter on read tools, and errorResult() for tool errors with isError: true.
Graph API compatibility notes
Legacy meta_search_places was removed because Meta retired Places Search. meta_search_targeting_geolocations finds advertising targeting locations, not replacement place IDs for tagging posts. The legacy fan-demographics tool now reports retired selectors without calling Graph API. Check current Page Insights documentation before choosing replacement metrics and periods.
Page reads retry once after error 190/subcode 2069032 when the failed token maps to exactly one cached Page. The client obtains a fresh token from the documented accounts list using the configured user token. It never refreshes or replays writes. Permission and refresh failures remain errors.