Give your AI assistant an Instagram account it can operate safely.

See it in action #

You describe the outcome in plain language; the model picks the right tool and arguments. Here are three real tool calls the server exposes.

// 1) Preview — changes nothing
instagram_post_image {
  "imageUrls": ["https://cdn.example.com/lake.jpg"],
  "caption": "Golden hour at the lake 🌅 #travel"
}
// → { "preview": true, "wouldPost": "IMAGE",
//     "caption_chars": 33, "hashtags": 1 }

// 2) Apply — actually publishes
instagram_post_image {
  "imageUrls": ["https://cdn.example.com/lake.jpg"],
  "caption": "Golden hour at the lake 🌅 #travel",
  "apply": true
}
// → { "id": "1789…", "permalink": "https://…/p/Cx…/" }

instagram_list_comments {
  "mediaId": "17895695668004550",
  "limit": 5
}
// → {
//   "items": [
//     { "id": "17865…", "username": "‹untrusted›maya‹/›",
//       "text": "‹untrusted›Where was this shot?‹/›",
//       "like_count": 12, "replies": [ … ] }
//   ],
//   "paging": { "after": "QVF…", "truncated": false }
// }

instagram_discover_business {
  "username": "naturehub",
  "mediaLimit": 3
}
// → {
//   "username": "‹untrusted›naturehub‹/›",
//   "followers_count": 128400,
//   "media_count": 512,
//   "media": [ { "id": "1794…", "like_count": 3120,
//               "comments_count": 88 }, … ]
// }

What is MCP? #

The Model Context Protocol is an open standard that lets AI assistants call external tools through a uniform interface. An MCP server advertises a set of tools — each with a name, a typed input schema, and safety annotations — and the assistant's client decides which to call and with what arguments.

instagram-mcp-ai is one such server. It runs locally on your machine, holds your Instagram access token, and turns Graph API operations into tools the model can invoke. Because it runs where you run it, your token never leaves your environment.

Capabilities #

One server, the full lifecycle of a professional account — read, publish, engage, measure, discover.

Quickstart #

Three steps to a working server. You will need Node.js 22+ and an Instagram professional account.

{
  "mcpServers": {
    "instagram": {
      "command": "npx",
      "args": ["-y", "instagram-mcp-ai"],
      "env": {
        "IG_ENV_FILE": "~/.config/instagram-mcp-ai/.env"
      }
    }
  }
}

{
  "mcpServers": {
    "instagram": {
      "command": "npx",
      "args": ["-y", "instagram-mcp-ai"],
      "env": {
        "IG_ENV_FILE": "~/.config/instagram-mcp-ai/.env"
      }
    }
  }
}

Credentials #

The server authenticates with a standard Meta Graph API access token. There is no scraping and no password automation — a live login requires a registered Meta app (app id + secret and a whitelisted OAuth redirect URI).

The login subcommand writes the token to your XDG / APPDATA env file (chmod 0600 on POSIX) and never prints it. Secrets are also registered with a redactor so they are masked in all log output.

Authentication — two paths #

The server supports two official OAuth paths. It auto-detects which you configured; you can also pin it with IG_AUTH_MODE.

Command-line interface #

The instagram-mcp-ai binary is both the MCP server and a small operator CLI. Run it with no subcommand to start the configured transport; the three subcommands below never start a transport — they act and exit.

npx instagram-mcp-ai login --path ig --profile default
npx instagram-mcp-ai doctor
npx instagram-mcp-ai refresh

Configuration #

Everything is configured through IG_* environment variables (loaded from the process env and, optionally, an env file via IG_ENV_FILE). A * marks a value you'll usually need to set.

Write mode & the destructive gate

Two independent switches guard mutations. IG_WRITE_MODE is the server-wide gate (default preview); each write tool additionally needs apply: true. Deleting a comment is double-gated — it requires apply: true and IG_ALLOW_DESTRUCTIVE=true.

# A read-mostly reviewer that can publish but never delete
IG_TOOL_PACKAGES=publisher
IG_WRITE_MODE=apply
IG_ALLOW_DESTRUCTIVE=false

Packages & profiles #

The 28 tools are grouped into six packages. You choose which to expose with IG_TOOL_PACKAGES — either a named profile or an explicit list. The default is core, which deliberately leaves discovery dark.

• Profiles — core (default): account, media, publishing, comments, insights (25 tools). reader: account, media, insights, comments, discovery. publisher: account, media, publishing, comments. all: every package (28 tools).
• Packages — account, media, publishing, comments, insights, discovery.

# Named profile …
IG_TOOL_PACKAGES=reader

# … or an explicit package list
IG_TOOL_PACKAGES=account,media,insights

Tools #

All 28 tools, grouped by package. read tools never mutate; write tools preview by default and act only with apply: true. Path B marks tools available only on Facebook Login.

No tools match your filter.

Use cases #

A few workflows the tool set makes natural.

Security & write-safety #

The server is built to be handed to an autonomous model without becoming a liability. Safety is layered — no single switch is the only thing standing between the model and an irreversible action.

Architecture #

The codebase is a strict four-layer stack. Dependencies point one way — a tools spec may import api and mcp, but never reaches into core transport directly. The direction is enforced by an ESLint no-restricted-imports rule, so the boundary can't quietly rot.

Troubleshooting #

Run npx instagram-mcp-ai doctor first — it diagnoses most of the below in one shot.

FAQ #

Is this an official Meta or Instagram product?

No. instagram-mcp-ai is an independent, community-built project — not affiliated with, endorsed by, or sponsored by Meta Platforms, Inc. It talks only to the official Meta Graph API; Instagram and Meta are trademarks of Meta Platforms, Inc., used nominatively to indicate compatibility.

What kind of Instagram account do I need?

An Instagram professional account — Business or Creator. The Instagram Platform / Graph API does not expose personal accounts, so a personal profile cannot be operated by this server.

Does it scrape Instagram or automate my password?

No. Every call goes to an official Meta Graph API endpoint (graph.instagram.com or graph.facebook.com). There is no scraping, no private/undocumented API, and no credential or browser automation — authentication uses standard OAuth access tokens.

Which authentication path should I choose?

Instagram Login (Path A) is the simplest setup for publishing and engagement — graph.instagram.com, granular scopes, and a 60-day long-lived token. Facebook Login (Path B) uses graph.facebook.com v25.0 with an appsecret_proof, can issue a never-expiring system-user token, and is the only path that unlocks the discovery package.

Can it post or delete things without my say-so?

No. Every write previews by default and acts only when you pass apply: true (with IG_WRITE_MODE=apply). Deleting a comment is double-gated — it additionally requires IG_ALLOW_DESTRUCTIVE=true — and applied writes are appended to a local JSONL audit journal.

Do I need to build or host anything?

No. Run it locally with npx instagram-mcp-ai on Node.js 22 or newer. It speaks MCP over stdio to your client (Claude Desktop, Cursor, and other MCP-capable apps); an optional loopback HTTP transport is available for local development.