claude-meta-mcp

Self-hosted Meta Ads (Facebook & Instagram) connector for Claude. Bring your campaign data into Claude conversations — no SaaS middleman, no per-seat pricing, your tokens stay on your server.

Status — v0.6.0 (single-tenant alpha). One Meta System User token, one shared Bearer secret, no database. Perfect for personal use or a single agency account. Multi-tenant + OAuth 2.1 + DCR are on the roadmap (see Roadmap).

v0.6 closes the file gap: images and videos reach the connector from a ChatGPT attachment (Apps SDK openai/fileParams), from a built-in upload page, or from any public URL — and get a stable, unguessable URL that Instagram publishing can use. v0.5 made ad sets fully steerable from a conversation: complete targeting spec on create and update (custom audiences, exclusions, placements, Advantage+ audience), promoted_object for conversion ad sets, audience / pixel lookups, a delivery estimate, and a safety layer — activation only through explicit set_*_status tools, budget raises need confirmation, optional hard caps. Every tool carries MCP annotations (readOnlyHint / destructiveHint) so clients can auto-approve reads. 57 tools across four surfaces — Ads, Pages, Instagram, Catalogs.

Why?

Existing options for connecting Meta Ads to Claude are either:

• SaaS-only (Windsor.ai, Pipeboard) — your ad data flows through a third-party platform, monthly fees, vendor lock-in.

• Local-only (most community MCP servers) — stdio transport, only works in Claude Desktop, can't be installed as a remote connector in claude.ai web.

claude-meta-mcp is a small, self-hostable Node service that:

• Speaks MCP Streamable HTTP, so it works with claude.ai web and Claude Desktop alike.

• Reads & writes Meta Ads (campaigns, ad sets, ads, creatives + image/video uploads), publishes & manages Facebook Page posts, publishes & moderates Instagram Business posts/reels/stories/carousels, and inspects Product Catalogs (feeds, products, diagnostics) for Dynamic Product Ads.

• Is MIT licensed — fork it, sell it, embed it.

Related MCP server: meta-ads-manager-mcp

Quick start

Prerequisites

• Node.js ≥ 20

• A Meta Developer App with a System User token. For the full v0.4 toolset that's ads_read, ads_management, business_management, pages_*, instagram_* and catalog_management scopes → see docs/META_APP_SETUP.md for the full step-by-step

• A public HTTPS URL (Claude requires HTTPS for custom connectors)

Install

git clone https://github.com/maxx3250/claude-meta-mcp.git
cd claude-meta-mcp
npm install
cp .env.example .env
# fill in META_ACCESS_TOKEN and generate AUTH_TOKEN:
echo "AUTH_TOKEN=$(openssl rand -hex 32)" >> .env
npm run build
node --env-file=.env dist/index.js

The server listens on PORT (default 3210) and exposes:

• GET /health — liveness probe (no auth)

• POST /mcp — MCP Streamable HTTP transport (Bearer auth)

Connect to Claude

1. Put the service behind a reverse proxy that terminates TLS — see docs/DEPLOYMENT.md.

2. In Claude → Settings → Connectors → Add custom connector.

3. URL: https://your-domain.example.com/mcp

4. Add header Authorization: Bearer <your AUTH_TOKEN> in the connector's advanced settings.

5. Save. Tools should appear in the connector list.

Available tools

57 tools in v0.6 across four surfaces — Ads (read + write), Facebook Pages (read + write), Instagram Business (read + write), Product Catalogs (read).

Safety (v0.5):

• Campaigns, ad sets and ads are always created PAUSED — there is no way to create something live.

• update_* tools cannot change a status. Going live is a separate, explicit call to set_campaign_status / set_adset_status / set_ad_status, so an MCP client shows it as its own confirmation.

• Raising a budget needs confirm_budget_increase: true; lowering never does. Optional hard caps MAX_DAILY_BUDGET_CENTS / MAX_LIFETIME_BUDGET_CENTS are enforced server-side and cannot be overridden from a conversation.

• Every tool is annotated: readOnlyHint on reads (clients such as ChatGPT developer mode auto-approve them), destructiveHint on deletes.

• Meta's rate limits (1 edit per object per 30 s, per-account bursts) are waited out and retried automatically.

Meta Ads — read

Meta Ads — write & assets

Getting images and videos into the connector

No chat client can hand raw file bytes to an MCP tool — the model only writes JSON. v0.6 gives you three ways in:

Files that did not come from a public URL are kept in the asset store (UPLOAD_DIR) and the upload tools return their asset_url, so the same file can go to Instagram afterwards (Meta fetches Instagram media from a public URL). The connector serves /upload only over loopback — your reverse proxy must authenticate it (nginx auth_basic with the same htpasswd as the OAuth shim is the natural fit, see docs/DEPLOYMENT.md). /assets/* is public but unguessable.

Facebook Pages (read & write)

Instagram Business (read & write)

Product Catalogs (read)

get_insights is the workhorse. Examples (in plain English from Claude):

• "What did we spend in the last 7 days, broken down by campaign?"

• "Compare CTR across publisher_platform breakdown for campaign 12345 last month."

• "Which ad sets had the worst CPM yesterday?"

Configuration

See .env.example.

How is this different from … ?

As of May 2026, based on each project's public README and pricing page. Names and trademarks belong to their respective owners; comparison is informational only.

Architecture (v0.6)

┌─────────────────────┐     POST /mcp        ┌──────────────────────────┐
│  Claude.ai / Desktop│ ──────────────────►  │  Express + MCP server    │
│                     │  Bearer AUTH_TOKEN   │  StreamableHTTPTransport │
└─────────────────────┘                      │           │              │
                                             │           ▼              │
                                             │  Meta Graph API client   │
                                             │  (axios, v26.0)          │
                                             └─────────────┬────────────┘
                                                           │
                                                           ▼
                                             https://graph.facebook.com

No database. No state between requests. One Meta System User token, one Bearer token, 57 tools. Optional asset store on disk when UPLOAD_DIR is set.

For sequence diagrams and the planned v1.0 multi-tenant architecture, see docs/ARCHITECTURE.md.

Roadmap

v0.2 — Pages support ✓ shipped

• list_pages, list_page_posts, get_page_insights, create_page_post, delete_page_post

v0.6 — Files in ✓ shipped

• ChatGPT attachments via openai/fileParams on upload tools + Instagram posting

• Asset store + /upload page + list_assets; HOST bind

v0.5 — Ad set steering + safety layer ✓ shipped

• Full targeting spec on create + update (merge / unset / replace), promoted_object, DSA fields

• get_adset, estimate_audience, audience + pixel lookups

• Explicit activation via set_*_status, budget-raise confirmation, hard caps, MCP annotations, rate-limit retry

v0.3 — Ads write + Instagram ✓ shipped

• Ads CRUD (campaigns, ad sets, ads, creatives)

• Image + video upload

• Instagram Business publishing (image / video / reel / story / carousel)

• Instagram comments (read / reply / delete / hide)

v0.4 — Product Catalogs (read) ✓ shipped (current)

• Business discovery via adaccount + page dedup

• Catalog + feed listing, single-catalog detail

• Product listing with availability/condition filters

• get_catalog_diagnostics (/{catalog_id}/diagnostics + feed-upload fallback)

v0.5 — Catalog writes + Signal Diagnostics

• create_product_catalog, create_product_feed, update_product_feed_schedule

• Pixel + CAPI health (list_pixels, get_pixel_stats, get_pixel_event_match_quality, get_capi_status)

v0.6 — proper auth

• OAuth 2.1 with Dynamic Client Registration on the Claude side

• .well-known/oauth-authorization-server discovery endpoint

• Token issuance + refresh

v0.7 — multi-tenant

• Meta OAuth user flow + 60-day token refresh

• SQLite (then Postgres) for user → meta-token mapping

• AES-256-GCM encryption at rest for stored tokens

v0.8 — performance

• Insights pre-aggregation cache with smart invalidation

• Background refresh for "yesterday and earlier" data

v1.0 — production-ready

• Audit log, rate limiting per tenant

• Prometheus /metrics endpoint

• Health checks for downstream Meta API

Stretch

• Google Ads connector under the same umbrella

• TikTok Ads connector

• LinkedIn Ads connector

Project layout

src/
├── index.ts             Express + MCP bootstrap, Bearer middleware
├── config.ts            Env validation
├── meta-client.ts       Graph API axios wrapper + pagination + multipart helpers
├── tools.ts             Read tools (Ads + Pages)
├── tools-write.ts       Ads write tools (campaigns/ad sets/ads/creatives + asset uploads)
├── tools-instagram.ts   Instagram Business tools (publish + comments + insights)
└── tools-catalogs.ts    Product Catalog read tools (businesses, catalogs, feeds, products, diagnostics)

docs/
├── ARCHITECTURE.md
├── DEPLOYMENT.md
└── META_APP_SETUP.md

ecosystem.config.cjs  pm2 example
.env.example          Configuration template

Development

npm run dev       # tsx watch mode
npm run build     # tsc → dist/
npm start         # node dist/index.js

Security notes

• The Bearer token in AUTH_TOKEN is a single shared secret. Anyone with it can mutate ad campaigns, publish/delete posts on your Facebook Pages and Instagram Business accounts, and read your product catalogs via the connector. Treat it like a database password.

• All write tools that create campaigns/ad sets/ads default to status: PAUSED. Activating an ad still costs nothing until you set status: "ACTIVE".

• The connector's scopes are additive. If you only want a read-only Ads experience, omit ads_management and the IG/Pages write scopes from your System User token — the matching tools will then fail with 403 at runtime.

• Always run behind HTTPS. Claude refuses to connect to non-TLS connectors anyway.

• Rotate AUTH_TOKEN by editing .env and restarting the process.

• Rotate META_ACCESS_TOKEN by revoking the System User token in Meta Business and minting a new one.

If you find a security issue, please email security@markusstoeger.com instead of opening a public issue.

Contributing

PRs welcome. See CONTRIBUTING.md for ground rules and CODE_OF_CONDUCT.md. Security issues should follow SECURITY.md, not the public issue tracker.

License

MIT © 2026 Markus Stöger

Acknowledgements

Inspired by the open MCP ecosystem and prior art in hashcott/meta-ads-mcp-server, pipeboard-co/meta-ads-mcp, and the Model Context Protocol team.