Meta MCP Server

Connect any AI assistant to Meta's entire business platform.
_{Facebook Pages · Instagram · Threads · Ads Manager · Commerce · Conversions API · Insights}

200 tools • 7 platforms • Graph API v21.0

Quick Start • What You Can Do • All 200 Tools • Configuration • Architecture

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

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 200 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

> 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

> 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

> 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

> 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

> 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?

> 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?

> 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?

> 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.

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.0 and graph.threads.net/v1.0 with separate base URLs and tokens
• Page token caching — meta_list_pages caches 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.

Contributing

Contributions welcome. Run the test suite and follow existing patterns:

npm test            # 52 tests
npm run build       # TypeScript compilation
npm run test:watch  # Development mode

Conventions: Zod .strict() schemas, response_format parameter on read tools, errorResult() for error returns with isError: true.

_{Not affiliated with or endorsed by Meta Platforms, Inc.}

_{Built by Oliver Ames in Vermont • GitHub • LinkedIn • Bluesky}