io.github.mikusnuz/meta
MCP server for Instagram Graph API, Threads API & Meta platform management
Open source Open in the app JSON README (API)
About
MCP server for Instagram Graph API, Threads API & Meta platform management
Details
- Kind
- MCP servers
- Topic
- Social & content
- Publisher
- mikusnuz
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 2.0.1
- Stars
- 24
- Forks
- 9
- Last push
- 2026-08-29T19:05:06Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:00:48
- Updated
- 2026-08-29 04:00:48
- Origin id
io.github.mikusnuz/meta
README
**English** | [한국어](README.ko.md)
# meta-mcp
[](https://www.npmjs.com/package/@mikusnuz/meta-mcp)
[](https://opensource.org/licenses/MIT)
[](https://lobehub.com/discover/mcp/mikusnuz-meta-mcp)
Full-coverage MCP server for **Instagram Graph API** (v26.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`](llms.txt) for a machine-readable summary, or copy [`templates/CLAUDE.md`](templates/CLAUDE.md) / [`templates/AGENTS.md`](templates/AGENTS.md) into your project for automatic MCP discovery.
## Features
- **66 tools** across Instagram (33), Threads (27), 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, ghost posts, reply approvals, location tags, and Instagram Stories cross-sharing; manage replies and pending reply approvals; search posts and locations; profile/mentions discovery; oEmbed; 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.1.0
- **Graph API v26.0**: Upgraded from v25.0 (no deprecated fields/endpoints from the v26.0 changelog were in use)
- **Tenor removed**: GIPHY is now the only GIF provider (Tenor was sunset March 31, 2026); `gif_provider` param dropped
- **Threads Ghost Posts**: `is_ghost_post` on `threads_publish_text` (auto-archived after 24h)
- **Threads Reply Approvals**: `enable_reply_approvals` on publish tools, plus `threads_get_pending_replies` and `threads_manage_pending_reply`
- **Threads → Instagram Stories cross-share**: `crossreshare_to_ig` / `crossreshare_to_ig_dark_mode` on all publish tools
- **Threads Location Tagging**: `location_id` on publish tools, plus `threads_search_locations` and `threads_get_location`
- **Threads Profile Discovery**: `threads_lookup_profile` and `threads_get_profile_posts` for public profiles
- **Threads Mentions**: `threads_get_mentions`
- **Threads oEmbed**: `threads_get_oembed` for embedding public posts
- **Threads Conversations**: `threads_get_conversation` for flattened (nested) reply threads
- **Fixed `threads_search_posts`**: now calls the correct `/keyword_search` endpoint with the correct `search_mode`/`search_type` parameters (previous version targeted a non-existent endpoint)
- Post/reply fields expanded with `is_verified`, `profile_picture_url`, `location_id`, `root_post`, `replied_to`, `reply_audience`
## 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](https://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",
"INSTAGRAM_MESSAGING_ACCESS_TOKEN": "your_page_access_token",
"INSTAGRAM_PAGE_ID": "your_linked_page_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",
"INSTAGRAM_MESSAGING_ACCESS_TOKEN": "your_page_access_token",
"INSTAGRAM_PAGE_ID": "your_linked_page_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 |
| `INSTAGRAM_MESSAGING_ACCESS_TOKEN` | For Instagram DMs | Page access token for Instagram Messaging with Facebook Login |
| `INSTAGRAM_PAGE_ID` | For Instagram DMs | Facebook Page ID linked to the Instagram professional account |
| `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` | Extend an Instagram/Facebook token or refresh a Threads token (`platform` selects the flow) |
| `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 (polls, GIFs, link attachments, topic tags, quote posts, spoiler flag, ghost posts, reply approvals, location tag, IG Stories cross-share) |
| `threads_publish_image` | Publish an image post (alt_text, topic tags, spoiler flag, reply approvals, location tag, IG Stories cross-share) |
| `threads_publish_video` | Publish a video post (alt_text, topic tags, spoiler flag, reply approvals, location tag, IG Stories cross-share) |
| `threads_publish_carousel` | Publish a carousel (2-20 items, alt_text per item, reply approvals, location tag, IG Stories cross-share) |
| `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 (4)
| Tool | Description |
|------|-------------|
| `threads_get_posts` | List published posts (includes topic_tag, poll, GIF, location, verification fields) |
| `threads_get_post` | Get post details |
| `threads_get_profile_posts` | List a public profile's posts by username (Profile Discovery) |
| `threads_search_posts` | Search public posts via `/keyword_search` by keyword or topic tag, filterable by media type and author |
### Threads — Replies (7)
| Tool | Description |
|------|-------------|
| `threads_get_replies` | Get top-level replies to a post |
| `threads_get_conversation` | Get all replies (flattened, including nested) 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_get_pending_replies` | Get replies awaiting approval on a post with reply approvals enabled |
| `threads_manage_pending_reply` | Approve or ignore a pending reply |
### Threads — Profile & Discovery (3)
| Tool | Description |
|------|-------------|
| `threads_get_profile` | Get Threads profile info (includes is_verified) |
| `threads_get_user_threads` | List user's threads |
| `threads_lookup_profile` | Look up a public profile by username (Profile Discovery) |
### Threads — Mentions (1)
| Tool | Description |
|------|-------------|
| `threads_get_mentions` | Get posts where the user was @mentioned |
### Threads — Locations (2)
| Tool | Description |
|------|-------------|
| `threads_search_locations` | Search for locations to tag, by query or coordinates |
| `threads_get_location` | Get a location object by ID |
### Threads — Tools & Resources (1)
| Tool | Description |
|------|-------------|
| `threads_get_oembed` | Get embed HTML/metadata for a public post |
### 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 (also available to Threads profiles without a linked Instagram account) |
## 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.
1. Go to [developers.facebook.com](https://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.
1. In your Meta App, go to **"Add Products"** → add **"Instagram Graph API"**
2. Go to **"Instagram Graph API" → "Settings"** and connect your Instagram Business account via a Facebook Page
3. Open the [Graph API Explorer](https://developers.facebook.com/tools/explorer/)
- Select your app
- Add permissions: `instagram_basic`, `instagram_content_publish`, `instagram_manage_comments`, `instagram_manage_insights`, `instagram_manage_contents`, `instagram_manage_messages`, `pages_show_list`, `pages_read_engagement`, `pages_manage_metadata`
- Click **"Generate Access Token"** and authorize
4. The generated token is short-lived (~1 hour). Exchange it for a long-lived token (~60 days):
```
GET https://graph.facebook.com/v26.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.
5. **Get your Instagram User ID** — call this with your token:
```
GET https://graph.facebook.com/v26.0/me/accounts?fields=id,name,access_token&access_token=YOUR_TOKEN
```
This returns your Facebook Pages. For each page, get the linked Instagram account:
```
GET https://graph.facebook.com/v26.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`).
For the DM tools, the matching Page's `id` is `INSTAGRAM_PAGE_ID` and its
`access_token` is `INSTAGRAM_MESSAGING_ACCESS_TOKEN`. Do not use the IG User
ID or the user token in their place.
### Step 3: Threads Setup
> Works with **any Threads account** (personal or business). Instagram account link is no longer required since September 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_keyword_search,threads_manage_mentions,threads_delete,threads_location_tagging,threads_profile_discovery
&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** — 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:
```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
INSTAGRAM_MESSAGING_ACCESS_TOKEN=EAA... # Page token from Step 2.5 (DM tools only)
INSTAGRAM_PAGE_ID=123456789012345 # Linked Facebook Page ID (DM tools only)
# 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_refresh_token` with `platform=instagram` (requires `META_APP_ID` and `META_APP_SECRET`)
- **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
```
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