npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@qaassim/instagram-mcp-server

v1.0.0

Published

MCP server for Meta's official Instagram Platform APIs — Instagram API with Instagram Login (graph.instagram.com) and Instagram API with Facebook Login (graph.facebook.com)

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

  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)

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