Back to Browse

Instagram MCP Server

Marketing & SocialLow Risk10.0MCP RegistryLocal
Free

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

10.0
Low Risk10.0Low Risk

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.

env_vars

Check that this permission is expected for this type of plugin.

HTTP Network Access

Connects to external APIs or services over the internet.

What You'll Need

Set these up before or after installing:

Long-lived Instagram access token: an IGAA... token on instagram_login, or a long-lived Page or User token with the instagram_* scopes on facebook_login.Required

Environment variable: IG_ACCESS_TOKEN

Which Meta API path to use. instagram_login needs no Facebook Page (37 tools). facebook_login needs a linked Page and adds hashtag search, business discovery, Page listing and media deletion (42 tools).Optional

Environment variable: IG_AUTH_MODE

Instagram professional account ID. Optional on instagram_login; required on facebook_login (find it with instagram_list_pages).Optional

Environment variable: IG_USER_ID

Graph API version to pin.Optional

Environment variable: IG_API_VERSION

Meta app ID. Needed only for instagram_get_token_info and instagram_refresh_token on facebook_login.Optional

Environment variable: IG_APP_ID

Meta app secret. Needed only for instagram_get_token_info and instagram_refresh_token on facebook_login.Required

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 GitHub

From the project's GitHub README.

instagram-mcp-server

npm version CI

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
Hostgraph.instagram.comgraph.facebook.com
Facebook Page requiredNoYes — and you must admin it
Scope familyinstagram_business_*instagram_* + pages_*
Tools registered3742
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
  1. In the App Dashboard, create an app and add the Instagram product.
  2. Under Instagram → API setup with Instagram Login, connect your Instagram professional account.
  3. In step 3 of that page, click Generate token next to your account. Copy the IGAA... token.
  4. Request these permissions for your app: instagram_business_basic, instagram_business_content_publish, instagram_business_manage_comments, instagram_business_manage_messages.
Facebook Login path
  1. Add the Instagram product and use API setup with Facebook Login.
  2. Link your Instagram professional account to a Facebook Page you administer.
  3. 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.
  4. Run the server once and call instagram_list_pages to find your Instagram account ID, then set it as IG_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)

ToolNotes
instagram_get_accountProfile plus a capability report for the active mode. Call this first.
instagram_get_publishing_limitQuota used of the 100-post / 24h cap
instagram_get_token_infodebug_token on facebook_login; liveness check on instagram_login
instagram_refresh_tokenExtends a long-lived token. Returns it — does not persist it.
instagram_list_pagesfacebook_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 fresh McpServer every call. createMcpHandler invokes 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 GraphClient lives at module scope and is closed over, so the factory stays cheap.
  • Tools are gated at registration, not at call time. In instagram_login mode the model never sees instagram_search_hashtag, so it cannot waste a turn discovering it does not work. instagram_get_account reports 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. GraphError exposes isAuthError / isPermissionError / isRateLimited for programmatic branching.
  • The token goes in the Authorization header 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

MIT

Reviews

No reviews yet

Be the first to review this server!