@mikusnuz/meta-mcp

v2.0.2

Published

18 days ago

MCP server for Instagram Graph API, Threads API & Meta platform management

0High
0Medium
0Low

mikusnuz

mcp meta instagram threads graph-api model-context-protocol ai claude

English | 한국어

meta-mcp

Full-coverage MCP server for Instagram Graph API (v25.0), Threads API, and Meta platform management.

When to Use

Tell your AI assistant things like:

"Post a photo to Instagram" — publish photos, videos, reels, stories, and carousels
"Publish a text post on Threads" — text posts with polls, GIFs, link attachments, and topic tags
"Get my Instagram follower count and insights" — account and post-level analytics
"Schedule a carousel post" — multi-image albums on Instagram (2-10) or Threads (2-20)
"Reply to comments on my latest post" — read and respond to comments on both platforms
"Cross-post to Instagram and Threads" — use the built-in content_publish prompt
"Get analytics for my Threads account" — views, likes, replies, reposts, quotes, clicks
"Manage Instagram DMs" — list conversations, read messages, send replies

AI Agent Integration: See llms.txt for a machine-readable summary, or copy templates/CLAUDE.md / templates/AGENTS.md into your project for automatic MCP discovery.

Features

57 tools across Instagram (33), Threads (18), 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; view insights; delete posts
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

What's New in v2.0.0

Graph API v25.0: Upgraded from v21.0 (expired Sep 2025) to v25.0 (current)
Fixed deprecated metrics: impressions, video_views, engagement replaced with views, reach, saved, shares
Threads polls: Create posts with interactive poll attachments
Threads GIFs: Attach GIFs from GIPHY or Tenor
Threads topic tags: Categorize posts with topic tags
Threads link attachments: Attach URL preview cards to text posts
Threads post search: Search public posts by keyword or topic tag
Threads post deletion: Delete posts (rate limited to 100/day)
Threads publishing limit: Check remaining quota
Threads quote posts: Quote other posts by ID
Threads spoiler flag: Mark content as spoiler
Threads alt text: Add accessibility descriptions to all media types
Threads new reply controls: parent_post_author_only and followers_only options
Instagram alt text: Support for photo, reel, and carousel items
Instagram collaboration invites: Query and respond to collab invites
Updated insights metrics: New clicks, reposts, reels_skip_rate metrics

Account Requirements

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

Installation

npx (Recommended)

{
  "mcpServers": {
    "meta": {
      "command": "npx",
      "args": ["-y", "@mikusnuz/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"
      }
    }
  }
}

Manual

git clone https://github.com/mikusnuz/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 | | THREADS_ACCESS_TOKEN | For Threads | Threads API access token | | THREADS_USER_ID | For Threads | Threads user ID | | META_APP_ID | For token/webhook tools | Meta App ID | | META_APP_SECRET | For token/webhook tools | Meta App Secret |

You only need to set the variables for the platforms you use. For example, if you only use Threads, just set THREADS_ACCESS_TOKEN and THREADS_USER_ID.

Tools

Meta Platform (6)

| Tool | Description | |------|-------------| | meta_exchange_token | Exchange short-lived token for long-lived token (~60 days) | | meta_refresh_token | Refresh a long-lived token before expiration | | 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) | | ig_publish_video | Publish a video post | | ig_publish_carousel | Publish a carousel/album (2-10 items, supports alt_text per item) | | ig_publish_reel | Publish a Reel (supports alt_text) | | 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 | | ig_get_media_insights | Get media analytics (views, reach, saved, shares) | | 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) | | ig_business_discovery | Look up another business account | | ig_get_collaboration_invites | Get pending collaboration invites | | ig_respond_collaboration_invite | Accept or decline collaboration invites |

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_comments | Get comments mentioning you | | 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 | | ig_get_message | Get message details |

Threads — Publishing (7)

| Tool | Description | |------|-------------| | threads_publish_text | Publish a text post (supports polls, GIFs, link attachments, topic tags, quote posts, spoiler flag) | | threads_publish_image | Publish an image post (supports alt_text, topic tags, spoiler flag) | | threads_publish_video | Publish a video post (supports alt_text, topic tags, spoiler flag) | | threads_publish_carousel | Publish a carousel (2-20 items, supports alt_text per item) | | threads_delete_post | Delete a post (max 100/day) | | threads_get_container_status | Check container processing status | | threads_get_publishing_limit | Check remaining publishing quota (250 posts/day) |

Threads — Media & Search (3)

| Tool | Description | |------|-------------| | threads_get_posts | List published posts (includes topic_tag, poll, GIF fields) | | threads_get_post | Get post details | | threads_search_posts | Search public posts by keyword or topic tag |

Threads — Replies (4)

| Tool | Description | |------|-------------| | threads_get_replies | Get replies to a post | | threads_reply | Reply to a post (supports image/video attachments) | | threads_hide_reply | Hide a reply | | threads_unhide_reply | Unhide a reply |

Threads — Profile (2)

| Tool | Description | |------|-------------| | threads_get_profile | Get Threads profile info (includes is_verified) | | threads_get_user_threads | List user's threads |

Threads — Insights (2)

| Tool | Description | |------|-------------| | threads_get_post_insights | Get post analytics (views, likes, replies, reposts, quotes, clicks) | | threads_get_user_insights | Get account-level analytics |

Resources

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

Prompts

| Prompt | Description | |--------|-------------| | content_publish | Cross-post content to Instagram and Threads | | analytics_report | Generate combined analytics report |

Setup Guide

Step 1: Create a Meta Developer App

All platforms (Instagram, Threads) require a Meta Developer App.

Go to developers.facebook.com and log in
Click "My Apps" → "Create App"
Select "Other" → "Business" (or "None" for personal use)
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.

In your Meta App, go to "Add Products" → add "Instagram Graph API"
Go to "Instagram Graph API" → "Settings" and connect your Instagram Business account via a Facebook Page
Open the Graph API Explorer
- Select your app
- Add permissions: instagram_basic, instagram_content_publish, instagram_manage_comments, instagram_manage_insights, instagram_manage_contents, pages_show_list, pages_read_engagement
- Click "Generate Access Token" and authorize

The generated token is short-lived (~1 hour). Exchange it for a long-lived token (~60 days):

GET https://graph.facebook.com/v25.0/oauth/access_token
  ?grant_type=fb_exchange_token
  &client_id=YOUR_APP_ID
  &client_secret=YOUR_APP_SECRET
  &fb_exchange_token=SHORT_LIVED_TOKEN

Or use the meta_exchange_token tool after setup.

Get your Instagram User ID — call this with your token:
```
GET https://graph.facebook.com/v25.0/me/accounts?access_token=YOUR_TOKEN
```
This returns your Facebook Pages. For each page, get the linked Instagram account:
```
GET https://graph.facebook.com/v25.0/{page-id}?fields=instagram_business_account&access_token=YOUR_TOKEN
```
The instagram_business_account.id is your INSTAGRAM_USER_ID (a numeric ID like 17841400123456789).

Step 3: Threads Setup

Works with any Threads account (personal or business). Instagram account link is no longer required since September 2025.

In your Meta App, go to "Add Products" → add "Threads API"
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

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
  &response_type=code

For local testing, use https://localhost/ as redirect URI (configure in App Settings → Threads API → Redirect URIs)

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

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

Get your Threads User ID — call this with your token:
```
GET https://graph.threads.net/v1.0/me?fields=id,username&access_token=YOUR_TOKEN
```
The id field is your THREADS_USER_ID (a numeric ID like 1234567890).

Step 4: Configure Environment Variables

Set only the variables for the platforms you use:

# Instagram (requires Business/Creator account)
INSTAGRAM_ACCESS_TOKEN=EAAxxxxxxx...     # Long-lived token from Step 2
INSTAGRAM_USER_ID=17841400123456789      # Numeric ID from Step 2.5

# Threads (any account)
THREADS_ACCESS_TOKEN=THQWxxxxxxx...      # Long-lived token from Step 3
THREADS_USER_ID=1234567890               # Numeric ID from Step 3.6

# Meta App (for token management & webhooks)
META_APP_ID=123456789012345              # From App Settings → Basic
META_APP_SECRET=abcdef0123456789abcdef   # From App Settings → Basic

Token Renewal

Access tokens expire after ~60 days. Refresh before expiration:

Instagram: Use meta_exchange_token with the current valid token

Threads: Use meta_refresh_token or call:

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

You can check token status anytime with meta_debug_token.

Deprecated Metrics (v22.0+)

The following Instagram metrics were deprecated in Graph API v22.0 (January 2025) and removed for all versions on April 21, 2025:

| Deprecated Metric | Replacement | |-------------------|-------------| | impressions | views | | video_views | views | | plays | views | | clips_replays_count | views | | engagement | saves + shares + likes + comments | | email_contacts | Removed (no replacement) | | phone_call_clicks | Removed (no replacement) | | text_message_clicks | Removed (no replacement) | | get_directions_clicks | Removed (no replacement) | | website_clicks | Removed (no replacement) | | profile_views | Removed (no replacement) |

License

MIT