meta-mcp

Enables AI assistants to manage Instagram and Threads accounts — publish content, handle comments, view insights, search hashtags, and manage DMs through the Meta Graph API.

Prerequisites

• Node.js 22+ (LTS recommended)

Quick Start

Add to your MCP client config:

{
  "mcpServers": {
    "meta": {
      "command": "npx",
      "args": ["-y", "@exileum/meta-mcp"],
      "env": {
        "INSTAGRAM_ACCESS_TOKEN": "your_ig_token",
        "INSTAGRAM_USER_ID": "your_ig_user_id",
        "THREADS_ACCESS_TOKEN": "your_threads_token",
        "THREADS_USER_ID": "your_threads_user_id"
      }
    }
  }
}

Only set the variables for the platforms you use.

Manual Installation

git clone https://github.com/exileum/meta-mcp.git
cd meta-mcp
npm install
npm run build

{
  "mcpServers": {
    "meta": {
      "command": "node",
      "args": ["/path/to/meta-mcp/dist/index.js"],
      "env": {
        "INSTAGRAM_ACCESS_TOKEN": "your_ig_token",
        "INSTAGRAM_USER_ID": "your_ig_user_id",
        "THREADS_ACCESS_TOKEN": "your_threads_token",
        "THREADS_USER_ID": "your_threads_user_id"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | INSTAGRAM_ACCESS_TOKEN | For Instagram | Instagram Graph API access token | | INSTAGRAM_USER_ID | For Instagram | Instagram Business/Creator account ID (numeric string, or "me" for the authenticated user) | | THREADS_ACCESS_TOKEN | For Threads | Threads API access token | | THREADS_USER_ID | For Threads | Threads user ID (numeric string, or "me" for the authenticated user) | | META_APP_ID | For token/webhook tools | Meta App ID (numeric string) | | META_APP_SECRET | For token/webhook tools | Meta App Secret | | META_API_VERSION | Optional | Meta Graph API version for Instagram and Facebook endpoints — defaults to v25.0 (verified 2026-05-06). Override only when Meta deprecates a version before meta-mcp ships a new release. Format: vMAJOR.MINOR (e.g., v26.0); malformed values fall back to the default with a stderr warning. OAuth token endpoints are unversioned and unaffected by this setting | | THREADS_API_VERSION | Optional | Threads API version — defaults to v1.0 (verified 2026-05-06). Threads runs a separate single-major-version track and is not bumped in lockstep with the Graph API. Same vMAJOR.MINOR format and fallback behavior as META_API_VERSION | | MCP_TRANSPORT | Optional | Transport to serve MCP over — stdio (default) or http. See HTTP Transport | | MCP_HTTP_PORT | Optional (http) | TCP port for the HTTP transport — defaults to 3000. Must be an integer 1–65535 | | MCP_HTTP_HOST | Optional (http) | Bind address for the HTTP transport — defaults to 127.0.0.1 (loopback only). Set to 0.0.0.0 to accept connections from other hosts (e.g. in Docker), but only behind a TLS/auth reverse proxy | | MCP_HTTP_ALLOWED_HOSTS | Optional (http) | Comma-separated host:port allowlist for DNS-rebinding protection. Defaults to loopback variants at the bound port; set this when binding to a non-loopback host so legitimate requests pass the Host check |

The server validates these at startup. Malformed values for INSTAGRAM_USER_ID, THREADS_USER_ID, or META_APP_ID cause the process to exit with Invalid meta-mcp configuration: …. Setting only one half of a credential pair (e.g., INSTAGRAM_ACCESS_TOKEN without INSTAGRAM_USER_ID) prints a stderr warning and continues; related tool invocations still fail at call time.

HTTP Transport

By default the server speaks MCP over stdio — the right choice for local clients (Claude Desktop, Claude Code, etc.). Set MCP_TRANSPORT=http to instead serve the SDK's Streamable HTTP transport, which enables remote/web-based MCP clients, cloud deployments, and multiple concurrent client sessions.

MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npx @exileum/meta-mcp

The server then listens on http://127.0.0.1:3000/mcp: POST to send messages, GET for the server→client SSE stream, DELETE to end a session. Each client gets an isolated session keyed by the Mcp-Session-Id header, so multiple clients can connect at once.

Security. The transport binds to 127.0.0.1 (loopback) by default and enables DNS-rebinding protection scoped to localhost, so it is not reachable off-host out of the box. To expose it to other machines (e.g. a container), set MCP_HTTP_HOST=0.0.0.0 and run it behind a reverse proxy that terminates TLS and handles authentication — the server itself performs no auth. When bound to a non-loopback address, set MCP_HTTP_ALLOWED_HOSTS to the host:port values clients will use so the Host-header check passes (otherwise rebinding protection is disabled with a stderr warning).

Account Requirements

| Platform | Account Type | Notes | |----------|-------------|-------| | Instagram | Business or Creator | Personal accounts cannot use the Graph API. Free to switch in settings | | Threads | Any account | Instagram link no longer required since Sep 2025 | | Meta (token/webhook) | Meta Developer App | Create at developers.facebook.com |

Features

• 58 tools across Instagram (33), Threads (19), and Meta platform (6)
• Instagram: Publish photos/videos/reels/stories/carousels with alt text, manage comments, view insights, search hashtags, handle DMs, manage collaboration invites
• Threads: Publish text/images/videos/carousels with polls, GIFs, topic tags, link attachments, alt text, spoiler flags; manage replies; search posts; delete posts; view insights
• Meta: Token exchange/refresh/debug, webhook management
• 2 resources: Instagram profile, Threads profile
• 2 prompts: Cross-platform content publishing, analytics report
• Rate limit tracking via x-app-usage header — and automatic client-side throttling at 80% (1s slowdown) / 90% (5s backoff) so a burst of tool calls stays under Meta's per-app quota
• Automatic retry for transient Meta API failures (HTTP 429/500/502/503/504, network errors, fetch timeouts) with exponential backoff and Retry-After honoring; tunable via MetaClient's maxRetries option (default 3, set to 0 to disable)
• Structured error responses with error_type (auth, validation, rate_limit, server, network, internal), HTTP status, Meta API code/subcode/type, and a remediation hint where actionable — see CHANGELOG.md for the JSON shape
• MCP server instructions sent during initialize so clients know required env vars, the two-step publish flow, expected video processing times, and the _rateLimit envelope without re-reading the README
• MCP notifications/progress emitted while polling container status during publishing — attach a progressToken to ig_publish_* / threads_publish_image|video|carousel calls and the server reports each poll attempt
• Structured MCP logging via the notifications/message channel (the server declares the logging capability) — each API call logs debug (method + path, never the token-bearing URL), terminal failures log error (status/code/sanitized message), rate-limit pressure logs warning, and DELETE/publish operations log an info audit line. Clients can raise the floor with logging/setLevel (default emits all levels, including debug)
• Optional HTTP transport — set MCP_TRANSPORT=http to serve the MCP Streamable HTTP transport (stateful multi-session, localhost-bound by default) instead of stdio, for remote/cloud deployments — see HTTP Transport

Tools

Meta Platform (6)

| Tool | Description | |------|-------------| | meta_exchange_token | Exchange short-lived token for long-lived token (~60 days). Requires platform (instagram or threads) | | meta_refresh_token | Refresh a long-lived token before expiration. Requires platform (instagram or threads) | | meta_debug_token | Inspect token validity, expiration, and scopes | | meta_get_app_info | Get Meta App information | | meta_subscribe_webhook | Subscribe to webhook notifications | | meta_get_webhook_subscriptions | List current webhook subscriptions |

Instagram — Publishing (6)

| Tool | Description | |------|-------------| | ig_publish_photo | Publish a photo post (supports alt_text, collaborators) | | ig_publish_video | [DEPRECATED] Use ig_publish_reel — publishes as a Reel (legacy VIDEO media_type retired by Meta Nov 9, 2023; supports collaborators) | | ig_publish_carousel | Publish a carousel/album (2-10 items, supports alt_text per IMAGE item, collaborators) | | ig_publish_reel | Publish a Reel (supports collaborators) | | ig_publish_story | Publish a Story (24hr) | | ig_get_container_status | Check media container processing status |

Instagram — Media (5)

| Tool | Description | |------|-------------| | ig_get_media_list | List published media | | ig_get_media | Get media details | | ig_delete_media | Delete a media post (requires Facebook Login) | | ig_get_media_insights | Get media analytics (default views, reach — override metric per media type) | | ig_toggle_comments | Enable/disable comments on a post |

Instagram — Comments (7)

| Tool | Description | |------|-------------| | ig_get_comments | Get comments on a post | | ig_get_comment | Get comment details | | ig_post_comment | Post a comment | | ig_get_replies | Get replies to a comment | | ig_reply_to_comment | Reply to a comment | | ig_hide_comment | Hide/unhide a comment | | ig_delete_comment | Delete a comment |

Instagram — Profile & Insights (5)

| Tool | Description | |------|-------------| | ig_get_profile | Get account profile info | | ig_get_account_insights | Get account-level analytics (views, reach, follower_count). Optional metric_type (total_value or time_series) controls aggregation shape | | ig_business_discovery | Look up another business account | | ig_get_collaboration_invites | Get pending collaboration invites | | ig_respond_collaboration_invite | Accept/decline a collaboration invite by media_id |

Instagram — Hashtags (4)

| Tool | Description | |------|-------------| | ig_search_hashtag | Search hashtag by name | | ig_get_hashtag | Get hashtag info | | ig_get_hashtag_recent | Get recent media for a hashtag | | ig_get_hashtag_top | Get top media for a hashtag |

Instagram — Mentions & Tags (2)

| Tool | Description | |------|-------------| | ig_get_mentioned_comment | Get details of a specific comment mentioning you (by comment_id from a mention webhook) | | ig_get_tagged_media | Get media you're tagged in |

Instagram — Messaging (4)

| Tool | Description | |------|-------------| | ig_get_conversations | List DM conversations | | ig_get_messages | Get messages in a conversation | | ig_send_message | Send a DM (optional messaging_type = RESPONSE/UPDATE/MESSAGE_TAG and tag = HUMAN_AGENT for the 7-day human-agent window) | | ig_get_message | Get message details |

Threads — Publishing (9)

| Tool | Description | |------|-------------| | threads_publish_text | Publish a text post in a single API call (auto_publish_text=true, default; set auto_publish=false for the legacy two-step flow). Supports polls, GIFs, link attachments, topic tags, quote posts, spoiler flag, cross-share to IG Stories, geo-gating via allowlisted_country_codes, location tagging via location_id, text attachments up to 10K chars with styling | | threads_publish_image | Publish an image post (supports alt_text, topic tags, spoiler flag, cross-share to IG Stories, geo-gating via allowlisted_country_codes, location tagging via location_id) | | threads_publish_video | Publish a video post (supports alt_text, topic tags, spoiler flag, cross-share to IG Stories, geo-gating via allowlisted_country_codes, location tagging via location_id) | | threads_publish_carousel | Publish a carousel (2-20 items, supports alt_text per item, cross-share to IG Stories, geo-gating via allowlisted_country_codes and location tagging via location_id on the parent container) | | threads_delete_post | Delete a post (max 100/day) | | threads_get_container_status | Check container processing status (unpublished containers only) | | threads_get_publishing_limit | Check remaining publishing quota (250 posts/day) | | threads_repost | Repost an existing thread to your profile (requires threads_content_publish) | | threads_search_locations | Search Threads-supported locations by query (q) or coordinates (latitude+longitude) to obtain a location_id for the four threads_publish_* tools (requires threads_location_tagging permission) |

Threads — Media & Search (3)

| Tool | Description | |------|-------------| | threads_get_posts | List published posts (includes topic_tag, poll, GIF fields; optional fields param to override the default field list) | | threads_get_post | Get post details | | threads_search_posts | Search public posts by keyword or tag (requires threads_keyword_search permission) |

Threads — Replies (4)

| Tool | Description | |------|-------------| | threads_get_replies | Get replies to a post (mode='top_level' default, or mode='full_tree' for the entire conversation flattened) | | threads_reply | Reply to a post (supports image/video attachments) | | threads_hide_reply | Hide a reply | | threads_unhide_reply | Unhide a reply |

Threads — Mentions (1)

| Tool | Description | |------|-------------| | threads_get_mentions | List posts where the user was @mentioned (requires threads_manage_mentions) |

Threads — Profile (1)

| Tool | Description | |------|-------------| | threads_get_profile | Get Threads profile info (includes is_verified and is_eligible_for_geo_gating) |

Threads — Insights (2)

| Tool | Description | |------|-------------| | threads_get_post_insights | Get post analytics (views, likes, replies, reposts, quotes, shares) | | threads_get_user_insights | Get account-level analytics (period: day/lifetime; since/until required for day) |

Resources

| Resource URI | Description | |-------------|-------------| | meta-mcp://instagram/profile | Instagram account profile data | | meta-mcp://threads/profile | Threads account profile data (includes is_verified and is_eligible_for_geo_gating) |

Prompts

| Prompt | Description | Arguments (all optional) | |--------|-------------|--------------------------| | content_publish | Cross-post content to Instagram and Threads | platform (instagram | threads | both), content_type (text | image | video | carousel), media_url, caption | | analytics_report | Generate combined analytics report | platform (instagram | threads | both), time_range (7d | 30d | 90d), focus (engagement | growth | content) |

Setup Guide

Step 1: Create a Meta Developer App

1. Go to developers.facebook.com and log in
2. Click "My Apps" -> "Create App"
3. Select "Other" -> "Business" (or "None" for personal use)
4. Enter an app name and create

Your META_APP_ID and META_APP_SECRET are in App Settings -> Basic.

Step 2: Instagram Setup

Requires an Instagram Business or Creator account. Switch for free in Instagram app -> Settings -> Account type. No Facebook Page linking required — this uses the Instagram API with Instagram Login.

1. In your Meta App, go to "Instagram" -> "API setup with Instagram business login"
2. In the "Generate access tokens" section, click "Add account" -> log in to your Instagram account
3. The generated token is long-lived (~60 days) — no exchange step needed. Copy it as your INSTAGRAM_ACCESS_TOKEN.
   • To refresh before expiry, use the meta_refresh_token tool with platform: "instagram", or:

     GET https://graph.instagram.com/refresh_access_token
       ?grant_type=ig_refresh_token
       &access_token=LONG_LIVED_TOKEN

4. Get your Instagram User ID:

   GET https://graph.instagram.com/v25.0/me?fields=user_id,username&access_token=YOUR_TOKEN

   The user_id is your INSTAGRAM_USER_ID.
5. Permissions are configured in your app's Instagram settings. Available scopes:
   • instagram_business_basic — required for all operations
   • instagram_business_content_publish — publishing photos, reels, carousels
   • instagram_business_manage_comments — reading and managing comments
   • instagram_business_manage_messages — DM conversations and messaging

Step 3: Threads Setup

Works with any Threads account. Instagram link no longer required since Sep 2025.

1. In your Meta App, go to "Add Products" -> add "Threads API"
2. Go to "Threads API" -> "Settings":
   • Add your Threads account as a Threads Tester under "Roles"
   • Accept the invitation in the Threads app: Settings -> Account -> Website permissions -> Invites
3. Generate an authorization URL:

   https://threads.net/oauth/authorize
     ?client_id=YOUR_APP_ID
     &redirect_uri=YOUR_REDIRECT_URI
     &scope=threads_basic,threads_content_publish,threads_manage_insights,threads_manage_replies,threads_read_replies,threads_share_to_instagram,threads_manage_mentions,threads_keyword_search
     &response_type=code

   For local testing, use https://localhost/ as redirect URI (configure in App Settings -> Threads API -> Redirect URIs).
4. After authorization, exchange the code for an access token:

   POST https://graph.threads.net/oauth/access_token
   Content-Type: application/x-www-form-urlencoded
   
   client_id=YOUR_APP_ID
   &client_secret=YOUR_APP_SECRET
   &grant_type=authorization_code
   &redirect_uri=YOUR_REDIRECT_URI
   &code=AUTHORIZATION_CODE

5. Exchange for a long-lived token (~60 days):

   GET https://graph.threads.net/access_token
     ?grant_type=th_exchange_token
     &client_secret=YOUR_APP_SECRET
     &access_token=SHORT_LIVED_TOKEN

6. Get your Threads User ID:

   GET https://graph.threads.net/v1.0/me?fields=id,username&access_token=YOUR_TOKEN

   The id field is your THREADS_USER_ID.

Token Renewal

Access tokens expire after ~60 days. Refresh before expiration (token must be at least 24h old):

• Instagram: Use meta_refresh_token with platform: "instagram", or call:

  GET https://graph.instagram.com/refresh_access_token
    ?grant_type=ig_refresh_token
    &access_token=CURRENT_LONG_LIVED_TOKEN

• Threads: Use meta_refresh_token with platform: "threads", or call:

  GET https://graph.threads.net/refresh_access_token
    ?grant_type=th_refresh_token
    &access_token=CURRENT_LONG_LIVED_TOKEN

When you rotate a token through meta_refresh_token or meta_exchange_token, the new token is automatically applied in-memory to the running MCP server — subsequent tool calls use it immediately, no server restart needed. The new token is still returned in the response so you can persist it in your environment for the next process restart. A single [meta-mcp] <Platform> access token updated in-memory after <tool>… line is logged to stderr when this happens.

Check token status anytime with meta_debug_token.

Troubleshooting

Tool failures return isError: true with a JSON body in content[0].text matching the envelope documented in CHANGELOG.md: { error: true, error_type, http_status, code, subcode, type, step, container_id, message, remediation, fbtrace_id, raw }. The fastest path to a fix is to read error_type and the Meta API code, then jump to the matching subsection below. The full code reference is the Meta Graph API error handling guide.

On the publish tools (ig_publish_*, threads_publish_*, threads_reply), errors also include step (container creation / processing / publishing, plus child container creation / child processing / parent container creation / parent processing on carousels) and container_id when one was created. The message mirrors them: "Publish photo failed at processing (container: 17889615324): Container processing timed out after 30s". Use these to decide whether to retry the publish, clean up an orphaned container, or treat the existing container as still reusable.

error_type: "auth" — expired, revoked, or under-scoped token

Triggered by Meta API codes 190, 10, 102, HTTP 401, or type: "OAuthException". Common messages:

• Error validating access token: Session has expired — long-lived tokens expire ~60 days after issue.
• Application does not have permission for this action — the token is missing a scope, or the account is not eligible (e.g., a Personal Instagram account on Graph API endpoints).

What to do:

1. Run meta_debug_token to inspect expires_at, is_valid, and scopes.
2. If the token is not yet expired but at least 24h old, refresh in place with meta_refresh_token (platform: "instagram" or "threads") — this extends the lifetime by another ~60 days. If the token is already expired, the refresh endpoint will reject it; regenerate a short-lived token from the Meta App dashboard and exchange it via meta_exchange_token (or run a full re-authorization for Threads).
3. If scopes are missing, regenerate the token with the required permissions:
   • Instagram: instagram_business_basic (always required) plus instagram_business_content_publish, instagram_business_manage_comments, instagram_business_manage_messages per feature.
   • Threads: threads_basic, threads_content_publish, threads_manage_insights, threads_manage_replies, threads_read_replies, threads_share_to_instagram, threads_manage_mentions, threads_keyword_search per feature.
4. If your Instagram account is Personal, switch to Business or Creator for free in the Instagram app (Settings → Account type and tools → Switch to professional account). The Graph API rejects Personal accounts.

error_type: "rate_limit" — application or user quota exhausted

Triggered by Meta API codes 4, 17, 32, 341, 613, the business-use-case range 80001–80008, or HTTP 429. Includes any OAuthException with code 4 / 17 (these are surfaced as error_type: "rate_limit", not "auth", despite the type field). MetaClient automatically retries HTTP 429 up to 3 times with exponential backoff and honors any Retry-After header — a rate_limit error reaching the caller means the retry budget was exhausted.

What to do:

1. Inspect the _rateLimit field on prior successful tool responses. callCount, totalCpuTime, and totalTime come from Meta's x-app-usage header; when any approaches 100 you are near the per-app threshold.
2. meta-mcp already self-throttles once max(callCount, totalCpuTime, totalTime) crosses 80% (1s slowdown) or 90% (5s backoff) — watch for the warning-level MCP log message (logger: "meta-client", with usage_pct and delay_ms) the server emits before each throttled call. Profile reads (ig_get_profile, threads_get_profile, and the matching meta-mcp://*/profile resources) and hashtag-name lookups (ig_search_hashtag) are also cached in-process for 5 minutes / 7 days respectively, with cache hits skipping the network entirely. If you are still hitting rate_limit errors despite all that, reduce request volume further.
3. Threads has hard daily quotas (250 publishes, 100 deletes) — query the remaining quota with threads_get_publishing_limit before bulk operations.

error_type: "validation" — bad parameter, wrong ID, or unsupported field

Triggered by Meta API codes 100, 200, 803, or any unmapped 4xx HTTP status. Common pitfalls:

• Wrong user ID format — INSTAGRAM_USER_ID and THREADS_USER_ID must be the numeric ID returned by GET /me?fields=user_id (Instagram) or GET /me?fields=id (Threads), or the literal "me" for the authenticated user. The Instagram username is not accepted.
• (#100) Messaging is not supported on ig_send_message / ig_get_conversations / ig_get_messages — the account does not have the messaging API enabled. Grant instagram_business_manage_messages on your token and ensure DMs are enabled in the Instagram app (Settings → Privacy → Messages).
• Deprecated publish endpoint — ig_publish_video was retired by Meta on Nov 9, 2023; use ig_publish_reel for video posts. ig_publish_story is required for Stories.
• Mutually exclusive Threads attachments — a threads_publish_text post can carry only one of text_attachment, poll_options, link_attachment, or gif_attachment; combining them is rejected at the schema level.
• Unsupported metric / fields for the resource — see the per-tool Meta docs (ig_get_media_insights lists per-media_type valid metrics in its description).

Other categories

• error_type: "server" (codes 1, 2, HTTP 5xx) — transient Meta outage. MetaClient already retried 500/502/503/504 up to 3 times with exponential backoff before surfacing this; check metastatus.com if it persists.
• error_type: "network" — fetch timed out or failed before reaching Meta. MetaClient already retried thrown network errors up to 3 times; verify outbound connectivity if the error keeps reappearing.
• error_type: "internal" — unexpected condition that did not map to a Meta error code. The raw field carries the sanitized original message; access_token, client_secret, and input_token values are scrubbed to *** before reporting.

API Stability

meta-mcp is consumed as an MCP server runtime, not as a library. The supported entry points are:

• npx @exileum/meta-mcp (recommended for end users)
• node dist/index.js (manual installation)

The single programmatic export from the package root, createSandboxServer(): McpServer, exists for the Smithery sandbox runner and is the only stable JavaScript/TypeScript API.

zod and other transitive runtime dependencies are internal and not part of meta-mcp's public API. No zod symbols, types, or schemas flow through dist/index.d.ts, so zod's version may change in any release — including major version bumps — without a corresponding meta-mcp major bump.

@modelcontextprotocol/sdk is the one exception: McpServer (the return type of createSandboxServer()) is imported from that package, so a breaking change to McpServer's public interface would also be a breaking change for meta-mcp's programmatic API. In practice the MCP SDK follows semver, so consumers can treat @modelcontextprotocol/sdk as an implicit peer dependency of the createSandboxServer export.

Only the package root (@exileum/meta-mcp) is a supported import target. Deep imports into the published dist/ tree (e.g. @exileum/meta-mcp/dist/schemas.js) are blocked by the package.json exports map for any spec-compliant resolver and are not part of the public API; they may be renamed, removed, or restructured in any release.

Glama

Contributing

Contributions are welcome. See CONTRIBUTING.md for the dev setup, project layout, the tool-registration recipe, testing, commit conventions, the CHANGELOG flow, and the CI gates. Bug reports and feature requests use the issue templates; pull requests use the PR template.

License

MIT

See CHANGELOG.md for release history.