Instagram MCP

instagram-mcp

MCP server for Instagram creators: publish, schedule, triage comments and DMs, and read insights with an AI agent, using only Meta's official Instagram API. Self-hosted; every write needs your approval.

Status: 1.0.0. Behaviour is specified in docs/CONTRACT.md and covered by a separate, code-blind test suite. It has been run end to end against real Meta on a test account (Facebook Login path, 2026-11-01): publishing, scheduling, comments, DMs, insights, webhooks and cleanup. Unified Login (the default for new apps) was also run end to end on 2026-11-01 with the app Live at Standard Access: setup, token, reads, publishing (URL and local files), scheduling, delete, comment writes, conversations, sending a DM to an Instagram Tester and the messaging profile. Not confirmed: real webhook events on the Unified path (Meta's Test event arrives, live comments and DMs did not; probably needs App Review); the Instagram Login path; collaboration invites and branded content; and actions that need another account's comment or @mention (hiding it, private replies, mention replies). Meta behaviours that are not well documented are listed in docs/TESTING-LIVE.md, and the server tolerates either answer.

Install

git clone https://github.com/pratikgh0se/instagram-mcp.git && cd instagram-mcp && npm ci && npm run build

Then follow Quick start, or docs/SETUP.md if you don't have a Meta app yet.

What it is

• Self-hosted. It runs on your machine (or your own server). Nothing is relayed through a third party. Tokens stay in your keychain or an encrypted file.
• Official Meta API only. No scraping, no private API, no password login, no browser automation.
• Secure by default. Local transport, bearer-protected HTTP, redacted logs, account allowlist, approval before every write. See Security model.
• Built for a creator workflow: 42 tools covering publishing and scheduling, comment triage, DMs, insights, reports, a media kit and competitor benchmarks.

Features

Full per-tool reference: docs/TOOLS.md (generated from the live registry).

What this cannot do (and why)

The official API does not offer these, so this server does not either.

• Follow or unfollow accounts.
• List your followers or who you follow.
• Like posts or comments, or save posts.
• Archive posts in the app (hide from profile).
• Pin posts or comments.
• Edit a caption after publishing.
• Read other people's private content, or download media from accounts that are not business or creator accounts you own.
• Run partnership ads (that is the Marketing API).
• Use Creator Marketplace (brand-side and requires App Review).

Known limitations

• Direct messages in Development mode (facebook login path): instagram_list_conversations returns an empty list until the other participant has a role on the app (the Instagram Tester role; see docs/SETUP.md section F). Confirmed 2026-11-01; see docs/CONTRACT.md U29.
• DM sending: in Development mode a send to an Instagram Tester failed with MESSAGING_WINDOW_CLOSED (Meta (#10), subcode 2534022) even inside the 24 h window; once the app was Live (still Standard Access) the same send succeeded (confirmed 2026-11-01, facebook path). Sending to people with no role on the app needs Advanced Access for instagram_manage_messages per Meta (App Review; not tested). Private replies to comments work.
• On the facebook path, real webhooks (comments and DMs) arrive only once the app is Live and subscribed to the Page (webhooks subscribe-page, default field feed, needs pages_manage_metadata; DMs need no extra permission). Going Live needs a public privacy policy page and data deletion page; templates and free hosting steps are in docs/legal/ and docs/SETUP.md section O.
• Unified Login: live-tested 2026-11-01 (app Live, Standard Access) for setup, token, reads, publishing, scheduling, delete, comment writes, conversations, DMs to an Instagram Tester and the messaging profile; hiding others' comments, private replies and @mention replies were confirmed 2026-11-02. Real webhook events were not delivered to a Unified app (Test event only; see Webhooks). Hashtag search needs App Review (Meta code 10).
• Instagram Login: Meta no longer offers the dashboard Instagram-login token to apps (confirmed 2026-11-01). The path remains for apps that already have it, and is not live-tested by the maintainer.
• instagram_get_profile returns account_type: null on the facebook and unified login paths (the Graph API does not provide it there); a warning says so.
• Mention replies work only for caption or comment @mentions, not photo tags.

Which login path

Each account is configured with one of three login paths. All use only official endpoints. Unified Login is the one to use for a new app without a Facebook Page; Meta no longer offers Instagram Login to apps.

"Probed" means the server tries the call and, if Meta refuses it, remembers that for the account and returns CAPABILITY_UNAVAILABLE naming the other path. Recommendation: Unified Login for a new app without a Page (needs a business portfolio), Facebook Login for the path verified end to end. docs/SETUP.md section B helps you choose.

Quick start

Requires Node.js 22.13 or newer. Installation is from source (the package is not published to npm yet).

git clone https://github.com/pratikgh0se/instagram-mcp.git

cd instagram-mcp npm ci npm run build

Optional: put the CLI on your PATH. Otherwise use node dist/cli.js wherever this README says instagram-mcp.

npm link

instagram-mcp accounts add --alias main --login unified # facebook path: --login facebook --page-id --app-id instagram-mcp auth set-token --account main # hidden prompt, or pipe it on stdin; ig_user_id is found automatically

facebook path only: instagram-mcp auth set-app-secret (hidden prompt; the token exchange needs it)

optional on unified: instagram-mcp auth set-app-secret --account main (per-account secret, useful with accounts from more than one Meta app)

instagram-mcp doctor

The unified path needs the token from the dashboard's "API setup with Unified login" (see docs/SETUP.md section H2); the app ID and Page ID are not needed. The facebook path needs three things: the Page ID, the app ID and the app secret. A Graph API Explorer token lasts about 1 hour, so run auth set-token right after generating it; without the app secret the long-lived exchange fails and the token expires within the hour.

Before this works you need a Professional Instagram account, a Meta app and a token. docs/SETUP.md walks through that from "no Meta developer account", step by step. doctor prints PASS, WARN or FAIL per check with a fix for each. If a feature wrongly reports CAPABILITY_UNAVAILABLE (a cached "no"), clear it with instagram-mcp capabilities reset --account .

Connect an MCP client

Use absolute paths. Replace /ABSOLUTE/PATH/TO/instagram-mcp with your clone. For Claude Desktop also use the absolute node path from command -v node (Desktop does not read your shell PATH, so an nvm-installed node is not found by a bare node).

Claude Desktop (claude_desktop_config.json):

{

"mcpServers": { "instagram": { "command": "/ABSOLUTE/PATH/TO/node", "args": ["/ABSOLUTE/PATH/TO/instagram-mcp/dist/cli.js", "serve"] } } }

Claude Code (stdio):

claude mcp add instagram -- node /ABSOLUTE/PATH/TO/instagram-mcp/dist/cli.js serve

HTTP mode (Streamable HTTP at /mcp, bearer required, loopback by default):

instagram-mcp http-token rotate        # prints a new bearer once; stores it in your secrets backend

instagram-mcp serve --http --port 8765

claude mcp add --transport http instagram http://127.0.0.1:8765/mcp --header "Authorization: Bearer <TOKEN>"

The server refuses to start in HTTP mode without a stored bearer, and refuses a non-loopback bind unless http.allow_remote is true. INSTAGRAM_MCP_HTTP_HOST overrides http.host (the --host flag wins over both); the allow_remote rule applies to the effective host.

Tip: set your client to ask before running instagram_approve and let everything else run. That one tool is the only one that changes Instagram.

Long approves: publishing a large carousel (up to 20 items) can take several minutes while Instagram processes each container. instagram_approve sends MCP progress notifications whenever the client suppl