instagram-mcp-ai — Instagram MCP Server

<!-- Badge note: the npm-version, downloads, node and Snyk badges resolve as of the 2026-08-25 publish of 0.7.0. The coverage badge still renders "not found" — Codecov is not enabled for this repo (it needs a token; see workplan T-R6) — and downloads will read 0 until the package has a month of history. That is expected (the block matches the published sibling servicenow-mcp-ai). -->

| | | | | | | :--: | :--: | :--: | :--: | :--: | | | | | | |

📖 Documentation site →

A locally-run, TypeScript Model Context Protocol server that exposes an Instagram professional account (Business/Creator) over the official Meta Graph API (graph.instagram.com / graph.facebook.com) — content publishing, media management, comment moderation, insights and discovery, as safe, well-annotated MCP tools. It talks only to official Meta endpoints: no scraping, no instagram-private-api-style clients, no cookie/session reuse. It ingests media by public HTTPS URL only. Credentials live in a local env file and can be obtained/refreshed with a built-in CLI.

Status: published to npm as instagram-mcp-ai@0.7.0 (2026-08-25). The read path (account, media, insights), the write path (content publishing, comment moderation) and discovery are all implemented, unit-tested and CI-green across Linux/macOS/Windows on Node 22 and 24. No tool has been exercised against a live Instagram account by CI — the suite is offline by construction, so what is proven is behaviour against recorded Graph shapes, not against Meta's live responses. That, not missing functionality, is what separates 0.7.0 from 1.0.0. The MCP-registry entry, the MCPB bundle and the plugin-marketplace listing are separate submissions and are not live yet. The documents under docs/ are the source of truth for the design.

Contents: What it does · Requirements · Quickstart · Setup · Configure credentials · Run / debug · Write safety · Package profiles · Tools · Configuration · Security notes · Project documentation · Support

Built and maintained in my own time — a GitHub Sponsors tip keeps it going.

What it does

The server exposes an Instagram professional account through 28 MCP tools grouped into six packages:

• Content publishing — feed images, 2–10 image carousels, Reels and Stories via the container → publish flow, plus one-call helpers (instagram_post_image / _reel / _story) and publishing-limit reporting.
• Media management — list/read own media (including album children) and toggle whether a post accepts comments.
• Comment moderation — list threads, reply, hide/unhide (reversible, preferred over delete) and delete; read tagged media.
• Insights — account and media metrics on the post-2025 views-based metric set, audience demographics and online-follower distribution.
• Discovery — hashtag search, hashtag top/recent media and public business/competitor discovery. (Path B / fb-login only — see below.)
• Account — profile, linked Facebook Pages / IG accounts, and a token-status report (auth path, expiry, days-left, refresh warning).

Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint) so clients apply the right confirmation UX, and every mutation passes through a preview-by-default write gate. All Graph URLs are pinned to a single API version (v25.0).

Why build it

The Meta ads niche is saturated — including Meta's own hosted Ads MCP (mcp.facebook.com/ads, ads-only) — while the organic Instagram side has only thin coverage. The existing TypeScript servers ship without tool annotations, structured output, token security or tests. A well-engineered TypeScript Instagram MCP server with proper token security, rate-limit compliance and honest Graph semantics fills that gap. It is a sibling of the planned facebook-mcp (Pages) server and shares the layered architecture of the production servicenow-mcp-ai.

The #1 constraint to know up front: Instagram ingests media by public URL — image_url / video_url must be reachable by Meta's servers. Publishing a local file means hosting it somewhere public first; v1 accepts URLs only.

Requirements

• Node.js ≥ 22 (Node 20 is EOL). Enforced by engines and a runtime guard in the CLI launcher with a clear message. CI runs the full gate on Node 22 and 24 across Linux, macOS and Windows.

Quickstart

Register the server with an MCP client (Claude Desktop, VS Code Chat, the Inspector…) by pointing the command at npx and supplying one auth path's credentials:

// claude_desktop_config.json / .mcp.json
{
  "mcpServers": {
    "instagram": {
      "command": "npx",
      "args": ["-y", "instagram-mcp-ai"],
      "env": {
        "IG_ACCESS_TOKEN": "<long-lived ig-login token>",
        "IG_ACCOUNT_ID": "<ig professional account id>"
      }
    }
  }
}

That is Path A (Instagram Login). For the token, the simplest path is the built-in login command — see Configure credentials. Everything else is optional tuning; the full list is under Configuration.

Setup

From source (for development):

npm install
npm run build

Or run the published package directly, without cloning:

npx instagram-mcp-ai

Credentials are read from ~/.config/instagram-mcp-ai/.env (XDG), the project .env, or real environment variables (which always win) — see below.

Two client-specific install channels wrap the same server: a Claude Desktop extension (docs/mcpb-install.md) and a Claude Code plugin (docs/plugin-install.md). Both prompt for the access token at install time and keep it in the OS keychain rather than in a settings file. The extension runs the server bundled inside the .mcpb; the plugin runs the npm package at the version its manifest pins, which resolves only once that version is published. Neither channel is listed yet: no .mcpb bundle has been released and the plugin is in no marketplace beyond this repo's own catalog. Each doc states its own status.

Configure credentials

All settings are environment variables with the uniform IG_ prefix; the canonical copy with inline comments is .env.example. Choose exactly one of the two Meta auth paths. Both read the account token from the same variable, IG_ACCESS_TOKEN — the path decides which host it is sent to and how it is signed:

| Path | IG_AUTH_MODE | Host | Also needs | Notes | | ---- | -------------- | ---- | ---------- | ----- | | A — Instagram Login | ig-login | graph.instagram.com | — | IG_ACCESS_TOKEN holds a long-lived IG-login token. appsecret_proof is not supported and never sent. The simplest path. | | B — Facebook Login | fb-login | graph.facebook.com | IG_APP_ID + IG_APP_SECRET | IG_ACCESS_TOKEN holds a Page / system-user token; requests carry an appsecret_proof HMAC. Required for the discovery tools (hashtag search, business discovery). |

With IG_AUTH_MODE unset the path is inferred: fb-login when both IG_APP_ID and IG_APP_SECRET are set, otherwise ig-login. Set it explicitly to override (IG_AUTH_PATH is accepted as an alias). Discovery tools are capability-filtered to Path B, so on Path A they are not registered at all.

login — obtain a long-lived token

A live login needs a registered Meta app (an app id/secret and a redirect URI whitelisted in the app's OAuth settings). With those in place:

# Path A (Instagram Login)
IG_APP_ID=... IG_APP_SECRET=... npx instagram-mcp-ai login --path ig

# Path B (Facebook Login)
IG_APP_ID=... IG_APP_SECRET=... npx instagram-mcp-ai login --path fb

It opens the browser, captures the loopback redirect, exchanges the code for a long-lived (~60-day) token and writes it to the env file (chmod 0600 on POSIX). No token or secret is ever printed. Run npx instagram-mcp-ai login --help for all options (--profile, --app-id, --app-secret, --account-id, --scopes, --redirect-uri). See docs/auth.md for the full token model, scopes and app setup.

Run / debug

The published instagram-mcp-ai binary (run it directly or via npx) has three subcommands; with no subcommand it starts the MCP server on the configured transport. All connection settings come from environment variables / the env file.

| Command | What it does | | ------- | ------------ | | instagram-mcp-ai | Starts the MCP server. Transport is stdio (default) or http, chosen by IG_TRANSPORT. | | instagram-mcp-ai login --path <ig\|fb> | One-time browser OAuth to obtain and persist a long-lived token (see above). | | instagram-mcp-ai doctor | Read-only health check for the active profile: config, token/auth, and one reachability GET. Exit 0 healthy, non-zero on failure. | | instagram-mcp-ai refresh | Refresh the active profile's long-lived token and write it back (ig_refresh_token on Path A, fb_exchange_token on Path B). | | instagram-mcp-ai --help | Prints this usage to stderr and exits 0. |

Anything else is a usage error: an unknown subcommand (docter), or an argument after doctor / refresh (they take none), is refused on stderr with exit 2 before any configuration is read — it never starts the server by accident.

• stdio (default) — for local MCP clients. stdout is the protocol channel; all diagnostics go to stderr.
• Streamable HTTP — opt in with IG_TRANSPORT=http. Loopback-bound (127.0.0.1:3000 by default via IG_HTTP_HOST / IG_PORT); set IG_HTTP_TOKEN to require an Authorization: Bearer <token> header (constant-time compared). Leaving IG_HTTP_TOKEN unset means no authentication at all — every local process can call every tool, writes included. It is allowed on loopback and logged at error level on startup; binding a non-loopback address without