Server data from the Official MCP Registry
Instagram via Meta's official Graph API: publishing, comments, DMs, insights and discovery.
About
Instagram via Meta's official Graph API: publishing, comments, DMs, insights and discovery.
Security Report
Valid MCP server (4 strong, 2 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry. Trust signals: 3 highly-trusted packages.
8 files analyzed · 1 issue found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
What You'll Need
Set these up before or after installing:
Environment variable: IG_ACCESS_TOKEN
Environment variable: IG_AUTH_MODE
Environment variable: IG_USER_ID
Environment variable: IG_API_VERSION
Environment variable: IG_APP_ID
Environment variable: IG_APP_SECRET
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"instagram-mcp-server": {
"command": "npx",
"args": [
"-y",
"@qaassim/instagram-mcp-server@1.0.0"
],
"env": {
"IG_APP_ID": "your-ig-app-id-here",
"IG_USER_ID": "your-ig-user-id-here",
"IG_AUTH_MODE": "your-ig-auth-mode-here",
"IG_APP_SECRET": "your-ig-app-secret-here",
"IG_API_VERSION": "your-ig-api-version-here",
"IG_ACCESS_TOKEN": "your-ig-access-token-here"
}
}
}
}Some servers take additional arguments. See the repository for details.
Documentation
View on GitHubFrom the project's GitHub README.
instagram-mcp-server
An MCP server for Meta's official Instagram Platform APIs. 37–42 tools covering publishing, media, comments, direct messages, insights, and discovery.
No private endpoints, no scraping, no session cookies, no username/password login.
Every call goes to graph.instagram.com or graph.facebook.com with an OAuth token
you issued yourself.
- TypeScript, MCP SDK v2 (
@modelcontextprotocol/server), Zod 4 - stdio and Streamable HTTP transports
- Graph API v26.0 by default, pinnable
- Supports both of Meta's Instagram configurations from one codebase
Which auth mode do you want?
Meta ships two different Instagram APIs. This server implements both; IG_AUTH_MODE
picks one at startup, and only the tools that mode can actually serve get registered.
instagram_login (default) | facebook_login | |
|---|---|---|
| Host | graph.instagram.com | graph.facebook.com |
| Facebook Page required | No | Yes — and you must admin it |
| Scope family | instagram_business_* | instagram_* + pages_* |
| Tools registered | 37 | 42 |
| Publishing, comments, DMs | ✅ | ✅ |
| Account and media insights | ✅ | ✅ |
| Mentions (read + reply) | ✅ | ✅ |
| Hashtag search | ❌ | ✅ |
| Business discovery (competitors) | ❌ | ✅ |
| Product tagging / Shopping | ❌ | ✅ |
| Delete media | ❌ | ✅ |
total_views / total_likes / total_comments metrics | ❌ | ✅ |
Pick instagram_login if your users should be able to connect with just an
Instagram account. The onboarding is dramatically simpler and it is Meta's
forward-looking path.
Pick facebook_login if you need hashtag research, competitor lookup, or
Shopping tags. There is no way to get those on the Instagram Login path — it is a
Meta product decision, not a gap in this server.
You can run two instances side by side with different modes if you need both.
Setup
1. Requirements
- Node.js 20.3 or newer
- An Instagram professional account — Business or Creator. Personal accounts cannot reach the Graph API at all.
- A Meta app at developers.facebook.com
2. Install
Nothing to install ahead of time. MCP clients can launch it straight from npm:
npx -y @qaassim/instagram-mcp-server
Run on its own, it exits and reports that IG_ACCESS_TOKEN is required. That is
expected. Your MCP client supplies the token through env (see step 5).
To install it globally instead:
npm install -g @qaassim/instagram-mcp-server
instagram-mcp-server
From source:
git clone https://github.com/qaassimq/instagram-mcp-server.git
cd instagram-mcp-server
npm install
npm run build
3. Create the Meta app and get a token
Instagram Login path
- In the App Dashboard, create an app and add the Instagram product.
- Under Instagram → API setup with Instagram Login, connect your Instagram professional account.
- In step 3 of that page, click Generate token next to your account. Copy the
IGAA...token. - Request these permissions for your app:
instagram_business_basic,instagram_business_content_publish,instagram_business_manage_comments,instagram_business_manage_messages.
Facebook Login path
- Add the Instagram product and use API setup with Facebook Login.
- Link your Instagram professional account to a Facebook Page you administer.
- Generate a long-lived User or Page token with:
instagram_basic,instagram_content_publish,instagram_manage_comments,instagram_manage_insights,instagram_manage_messages,instagram_manage_contents,pages_show_list,pages_read_engagement,business_management. - Run the server once and call
instagram_list_pagesto find your Instagram account ID, then set it asIG_USER_ID.
4. Configure
cp .env.example .env
# fill in IG_ACCESS_TOKEN, and IG_USER_ID if using facebook_login
5. Register with a client
Claude Desktop (claude_desktop_config.json) or any stdio MCP client:
{
"mcpServers": {
"instagram": {
"command": "npx",
"args": ["-y", "@qaassim/instagram-mcp-server"],
"env": {
"IG_ACCESS_TOKEN": "IGAA...",
"IG_AUTH_MODE": "instagram_login"
}
}
}
}
From a source checkout, use "command": "node" and
"args": ["/absolute/path/to/instagram-mcp-server/dist/index.js"] instead.
For a remote deployment:
TRANSPORT=http PORT=3000 npm start
# -> http://127.0.0.1:3000/mcp
The HTTP handler validates Host and Origin on localhost binds. Add bearer auth
before exposing it beyond localhost — see requireBearerAuth in the
SDK authorization docs.
The token in IG_ACCESS_TOKEN grants write access to a real Instagram account;
an unauthenticated public endpoint hands that to anyone who finds it.
6. Verify
npm run smoke # 19 checks, no live credentials needed
npx @modelcontextprotocol/inspector node dist/index.js # interactive
Tools
Account and auth (4–5)
| Tool | Notes |
|---|---|
instagram_get_account | Profile plus a capability report for the active mode. Call this first. |
instagram_get_publishing_limit | Quota used of the 100-post / 24h cap |
instagram_get_token_info | debug_token on facebook_login; liveness check on instagram_login |
instagram_refresh_token | Extends a long-lived token. Returns it — does not persist it. |
instagram_list_pages | facebook_login only. Finds your IG_USER_ID. |
Publishing (7)
instagram_publish_image · instagram_publish_reel · instagram_publish_story ·
instagram_publish_carousel · instagram_create_container ·
instagram_get_container_status · instagram_publish_container
The four high-level tools run Meta's whole create → process → publish flow. If video
processing outlasts wait_seconds they return the container ID instead of failing,
so an upload is never lost — finish it with instagram_get_container_status then
instagram_publish_container. instagram_create_container is the escape hatch for
parameters the high-level tools do not expose.
Media (5–6)
instagram_list_media · instagram_get_media · instagram_get_media_children ·
instagram_list_stories · instagram_list_tagged_media ·
instagram_delete_media (facebook_login only)
Comments (8)
instagram_list_comments · instagram_get_comment ·
instagram_list_comment_replies · instagram_create_comment ·
instagram_reply_to_comment · instagram_hide_comment ·
instagram_delete_comment · instagram_toggle_media_comments
Direct messages (5)
instagram_list_conversations · instagram_get_conversation ·
instagram_send_message · instagram_send_media_message · instagram_mark_seen
instagram_get_conversation reports whether the 24-hour reply window is still open,
so you can tell a refusal from a policy limit before you try to send.
Insights (5)
instagram_list_metric_catalog · instagram_get_account_insights ·
instagram_get_media_insights · instagram_get_audience_demographics ·
instagram_get_story_insights
Metric names change between Graph API versions and an unsupported metric or an
invalid metric/breakdown pair is a hard API error. instagram_list_metric_catalog
makes no API call and lists exactly what is valid, so the model looks names up
instead of guessing. Invalid pairs are rejected locally, before the round-trip.
instagram_get_story_insights reads every live story in one call — story insights
disappear with the story after 24 hours.
Discovery (3–6)
instagram_get_mentioned_comment · instagram_get_mentioned_media ·
instagram_reply_to_mention
and on facebook_login only: instagram_search_hashtag ·
instagram_get_hashtag_media · instagram_business_discovery
There is no "list all mentions" tool, because Meta has no such endpoint. Mentions
are delivered to your app through the mentions webhook field and then read by ID.
Without a webhook you cannot discover mentions through the API. Photo tags are a
different edge and can be listed — that is instagram_list_tagged_media.
Limitations you inherit from the Graph API
None of these are implementation gaps. They are Meta's constraints, and no MCP wrapper can route around them.
Account type. Instagram professional accounts only. Personal accounts have no Graph API access whatsoever.
App Review. Serving only your own business needs no review — Standard Access
covers it. The moment your app touches another business's account you need
Advanced Access, which means App Review: app icon, privacy policy, category, test
credentials, and an English screencast per permission. instagram_manage_messages
is the one that bites first, so DMs will not work for third parties until you pass
review.
Publishing. 100 API-published posts per rolling 24 hours, per account; a carousel
counts as one. JPEG is the only supported image format. Media must sit at a public
HTTPS URL that returns the file directly — Meta fetches it server-side, so local
paths, authenticated URLs, redirects and expiring signed URLs all fail. No filters,
no Shopping tags, no branded-content tags. alt_text works on image posts but not
on reels or stories.
Rate limits. Instagram Platform endpoints run on a Business Use Case limit of
4800 × impressions per 24 hours, where impressions is how many times the account's
content hit a screen in the last day. A low-reach account is a low-quota account —
your budget scales with the audience you already have, not with your needs. Business
Discovery and Hashtag Search sit outside this and fall under standard Platform Rate
Limits instead.
Hashtag search. 30 unique hashtags per rolling 7 days per account. Resolve a
hashtag to its ID once and reuse the ID. recent_media only covers the last 24
hours, and personal-account posts are never returned.
Insights. Carousel albums have no per-child insights. Audience demographics are
withheld below roughly 100 followers (an empty result, not an error). impressions
was replaced by views for media created after 2024-07-02.
Messaging. A standard reply is only allowed within 24 hours of the user's last
message. The HUMAN_AGENT tag extends that to 7 days. Unsolicited DMs are not
possible. Recipients are addressed by Instagram-scoped ID (IGSID) from a conversation
or webhook — never by public username.
Version churn. Meta retires a Graph API version roughly two years after release;
v26.0 shipped 2026-07-29. Pin IG_API_VERSION and treat upgrades as recurring work.
Architecture
src/
index.ts createServer() factory + transport selection
config.ts environment resolution, auth-mode validation
constants.ts every documented Meta constraint, cited to its doc
graph.ts dual-host client, error mapping, cursor pagination
format.ts markdown/JSON switch, character-limit guard, renderers
tools/
account.ts identity, capabilities, quota, token lifecycle
publishing.ts container create → poll → publish
media.ts feed, single media, carousel children, stories, tags
comments.ts read and moderate
messaging.ts Instagram Direct
insights.ts account, media, demographics, stories, metric catalog
discovery.ts mentions, hashtags, business discovery
scripts/
smoke.ts 19-check self-test
Design notes worth knowing if you extend it:
createServer()returns a freshMcpServerevery call.createMcpHandlerinvokes it per HTTP request; a shared instance passes manual testing and then fails under concurrency with-32603. The smoke test fires concurrent HTTP requests specifically to catch that regression.- The
GraphClientlives at module scope and is closed over, so the factory stays cheap. - Tools are gated at registration, not at call time. In
instagram_loginmode the model never seesinstagram_search_hashtag, so it cannot waste a turn discovering it does not work.instagram_get_accountreports what is missing and why. - Error text is written for the model. Meta's own message is preserved, the
numeric code is kept, and a recovery sentence plus the failing call site are
appended.
GraphErrorexposesisAuthError/isPermissionError/isRateLimitedfor programmatic branching. - The token goes in the
Authorizationheader on reads and in the form body on writes, so it never lands in a logged query string on a mutation. - Responses stay under 25,000 characters by returning fewer items, never by truncating text — the pagination cursor is suppressed when items are dropped so nothing is silently skipped.
License
Reviews
No reviews yet
Be the first to review this server!
More Marketing & Social MCP Servers
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
MCP Marketplace
Freeby mcp-marketplace · Developer Tools
Search and install MCP servers from inside your AI client.
mcp-creator-python
Freeby mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Lharries · Communication
Read, search, and send WhatsApp messages through your AI assistant
FinAgent
Freeby mcp-marketplace · Finance
Free stock data and market news for any MCP-compatible AI assistant.
Memory
Freeby Modelcontextprotocol · Productivity
Knowledge graph-based persistent memory across sessions
