io.github.mikusnuz/meta

Official

by mikusnuz · TypeScript

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

Manage Instagram, Threads, and Meta platforms via Graph API and Threads API.

Topics

ai-toolsgraph-apiinstagrammcpmcp-servermetamodel-context-protocolsocial-mediathreads

README.md15 KBView on GitHub

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)

json

{
  "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

bash

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

json

{
  "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):

code

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:
code
```
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:
code
```
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:

code

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:

code

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

code

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:
code
```
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:

bash

# 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:

code

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

Install

Configuration

Environment variables

INSTAGRAM_ACCESS_TOKENsecret

Instagram Graph API access token

INSTAGRAM_USER_ID

Instagram Business/Creator account ID

THREADS_ACCESS_TOKENsecret

Threads API access token

THREADS_USER_ID

Threads user ID

META_APP_ID

Meta App ID for token/webhook tools

META_APP_SECRETsecret

Meta App Secret for token/webhook tools

claude_desktop_config.json

{
  "mcpServers": {
    "meta": {
      "command": "npx",
      "args": [
        "-y",
        "@mikusnuz/meta-mcp@2.0.1"
      ],
      "env": {
        "INSTAGRAM_ACCESS_TOKEN": "<YOUR_INSTAGRAM_ACCESS_TOKEN>",
        "INSTAGRAM_USER_ID": "<YOUR_INSTAGRAM_USER_ID>",
        "THREADS_ACCESS_TOKEN": "<YOUR_THREADS_ACCESS_TOKEN>",
        "THREADS_USER_ID": "<YOUR_THREADS_USER_ID>",
        "META_APP_ID": "<YOUR_META_APP_ID>",
        "META_APP_SECRET": "<YOUR_META_APP_SECRET>"
      }
    }
  }
}