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

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.

Account Requirements

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

• 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

Tools

Meta Platform (6)

Instagram — Publishing (6)

Instagram — Media (5)

Instagram — Comments (7)

Instagram — Profile & Insights (5)

Instagram — Hashtags (4)

Instagram — Mentions & Tags (2)

Instagram — Messaging (4)

Threads — Publishing (8)

Threads — Media & Search (3)

Threads — Replies (4)

Threads — Mentions (1)

Threads — Profile (1)

Threads — Insights (2)

Resources

Prompts

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

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

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

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 callCount approaches 100 you are near the per-app threshold.

2. Back off with exponential delay; reduce request volume; cache profile metadata between calls.

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; retry with exponential backoff. Check metastatus.com if it persists.

• error_type: "network" — fetch timed out or failed before reaching Meta. Verify outbound connectivity and retry.

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