instagram-mcp-ai — Instagram MCP Server

📖 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: implementation complete and tested — not yet published to npm. 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. The published npm package and the live badges follow once npm publish runs. 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.

Related MCP server: instagram-mcp

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.

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 (set IG_AUTH_MODE only when both tokens are present):

When only one token is set the mode is auto-detected. 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, --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.

• 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).

Write safety

Every mutating tool passes through a single write gate (design gate D3):

• Preview by default. A write returns a non-mutating preview describing exactly what would change; nothing is sent to Meta.

• Apply explicitly. Pass apply: true on the call, or set IG_WRITE_MODE=apply for standing consent, to actually perform the write.

• Destructive ops are double-gated. Irreversible actions (e.g. instagram_delete_comment) additionally require IG_ALLOW_DESTRUCTIVE=true.

• Journaled. Every applied write is appended to a local, append-only JSONL journal (~/.local/state/instagram-mcp-ai/writes.jsonl, or IG_WRITE_JOURNAL) for auditing — best-effort, so a broken journal never fails an authorized write.

Package profiles

Tools are grouped into packages so you can expose only what a client needs (fewer tools keep the model focused). Set IG_TOOL_PACKAGES to a profile name or an explicit comma list of packages:

The six packages are account, media, insights, publishing, comments and discovery. Two more knobs refine a selection: IG_PACKAGES_DENY removes packages after the profile resolves, and IG_PACKAGES_READONLY forces a package's write tools off (its read tools stay). Auth-path capability filtering runs on top — a reader profile on Path A drops the three fb-login-only discovery tools.

Tools

The full v1 tool surface, generated from the tool registry — do not edit the table by hand; run npm run gen:readme. Auth paths is the login path a tool is valid for (both when unrestricted); Access is Read for read-only tools and Write for mutating ones (writes preview by default — see Write safety).

Configuration

All settings are environment variables with the uniform IG_ prefix; the canonical copy with inline comments is .env.example, and the table below is generated from it — do not edit it by hand; run npm run gen:readme. Real environment variables always take precedence over the file. Writes preview by default; set IG_WRITE_MODE=apply (and IG_ALLOW_DESTRUCTIVE=true for deletes) to perform them.

Project identity

Note on names: the npm package and MCP registry entry use instagram-mcp-ai (the unscoped instagram-mcp was already squatted on npm); the GitHub repository and the local working folder are instagram-mcp. The difference is cosmetic and does not affect the build or runtime.

Non-goals

• Ads / Marketing API — covered by Meta's official Ads MCP; out of scope permanently.

• Unofficial APIs — no instagram-private-api-style clients, no cookie/session reuse, no scraping. Official Graph API only.

• Consumer (personal) accounts — the Instagram Platform API only serves professional (Business/Creator) accounts; this server does not work around that.

• Multi-tenant SaaS hosting — this is a personal, locally-run server (single operator, one or few accounts). Streamable HTTP stays loopback-bound.

Security notes

• The env file is git-ignored and written owner-only (0600) — it holds plaintext tokens/secrets; do not commit real credentials.

• The server uses the stdio transport by default and only logs to stderr. Access tokens, app secrets and appsecret_proof HMACs are masked by a secret redactor before anything reaches a log sink; the login/refresh/doctor commands never print a token or secret.

• SSRF guard: Graph calls are restricted to the two allowlisted hosts (graph.instagram.com, graph.facebook.com) with the API version pinned, so a redirected or mistyped host cannot silently receive a token.

• Media ingestion is URL-only and by public HTTPS URL — no local files are uploaded, so the server never exfiltrates local content.

• Writes are preview-by-default, applied writes are journaled, and irreversible ops need a second explicit gate (IG_ALLOW_DESTRUCTIVE). See Write safety and docs/security.md.

Project documentation

The rendered documentation site mirrors these documents.

Support

This project is built and maintained in my own time. If it saves you or your team time, please consider supporting its continued development — sponsorship directly funds new tools, bug fixes and keeping pace with Meta's Graph surface.

• GitHub Sponsors — one-off or recurring, with no platform fee taken out (the preferred option).

• Ko-fi — quick one-off support; it also accepts PayPal, so it's the fallback for anyone without a GitHub account.

• Donate (Donatree) — a no-account donation page (card, PayPal and more) for a one-off tip.

Trademark

Instagram and Meta are trademarks of Meta Platforms, Inc. This project is independent and not affiliated with or endorsed by Meta. The marks are used only nominatively — to identify the platform this software interoperates with. This project is licensed under the MIT License; that license covers the source code and grants no rights to use the Instagram or Meta trademarks.