instagram-mcp-ai MCP server
Commit Nov 14, 2026Exposes an Instagram professional account via the Meta Graph API to allow AI agents to publish content, moderate comments, and analyze insights.
Also known as IvanBBaev/instagram-mcp
- Stars
- 7
- Tools
- 35
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- MIT
What is instagram-mcp-ai MCP?
instagram-mcp-ai exposes an Instagram professional account via the Meta Graph API to allow AI agents to publish content, moderate comments, and analyze insights. It exposes 35 tools, such as instagram_get_account, instagram_get_accounts_overview, instagram_list_linked_accounts.
Summary generated from the project's README
About instagram-mcp-ai MCP server
Managing organic Instagram presence through AI agents is possible with this MCP server. It connects to Instagram professional accounts via the official Meta Graph API, allowing users to publish content, moderate engagement, and analyze performance metrics directly from an AI client. The server operates locally using Node.js and communicates with official Meta endpoints rather than using scraping methods.
Users can perform a wide range of tasks including posting images, carousels, Reels, and Stories, as well as managing comments through replying, hiding, or deleting. It also provides access to account insights like audience demographics and media metrics. For advanced discovery, the server supports hashtag searches and business discovery when configured with Facebook Login credentials. Setup requires an Instagram professional account and an access token, which can be managed through a built-in CLI tool.
What you can do with it
- 1Automated content publishingAn AI agent can schedule and post various media types like Reels or image carousels to an Instagram feed.
- 2Community engagement and moderationA developer can task an AI with monitoring and responding to user comments on specific posts.
- 3Performance and audience analysisAn AI client can retrieve detailed metrics to understand follower distribution and media reach.
- 4Market and hashtag researchUsers can use an AI to find trending content or discover competitor business profiles.
Written from the project's README. Every use case is checked against a quote from it.
instagram-mcp-ai MCP tools 35
Detected from the READMEinstagram_get_accountinstagram_get_accounts_overviewinstagram_list_linked_accountsinstagram_token_statusinstagram_get_mediainstagram_list_mediainstagram_list_storiesinstagram_get_account_insightsinstagram_get_audience_demographicsinstagram_get_media_insightsinstagram_get_online_followersinstagram_create_media_container
| instagram_get_account | — | |
| instagram_get_accounts_overview | — | |
| instagram_list_linked_accounts | — | |
| instagram_token_status | — | |
| instagram_get_media | — | |
| instagram_list_media | — | |
| instagram_list_stories | — | |
| instagram_get_account_insights | — | |
| instagram_get_audience_demographics | — | |
| instagram_get_media_insights | — | |
| instagram_get_online_followers | — | |
| instagram_create_media_container | — |
Show all 35 toolsShow fewer tools
instagram_delete_mediainstagram_get_container_statusinstagram_get_publishing_limitinstagram_post_imageinstagram_post_reelinstagram_post_storyinstagram_publish_mediainstagram_create_commentinstagram_delete_commentinstagram_get_commentinstagram_get_mentioned_commentinstagram_get_mentioned_mediainstagram_hide_commentinstagram_list_comment_repliesinstagram_list_commentsinstagram_list_tagged_mediainstagram_reply_to_commentinstagram_set_comments_enabledinstagram_unhide_commentinstagram_discover_businessinstagram_get_hashtag_mediainstagram_list_recently_searched_hashtagsinstagram_search_hashtag
| instagram_delete_media | — | |
| instagram_get_container_status | — | |
| instagram_get_publishing_limit | — | |
| instagram_post_image | — | |
| instagram_post_reel | — | |
| instagram_post_story | — | |
| instagram_publish_media | — | |
| instagram_create_comment | — | |
| instagram_delete_comment | — | |
| instagram_get_comment | — | |
| instagram_get_mentioned_comment | — | |
| instagram_get_mentioned_media | — | |
| instagram_hide_comment | — | |
| instagram_list_comment_replies | — | |
| instagram_list_comments | — | |
| instagram_list_tagged_media | — | |
| instagram_reply_to_comment | — | |
| instagram_set_comments_enabled | — | |
| instagram_unhide_comment | — | |
| instagram_discover_business | — | |
| instagram_get_hashtag_media | — | |
| instagram_list_recently_searched_hashtags | — | |
| instagram_search_hashtag | — |
Configuration
IG_ACCESS_TOKENIG_ACCOUNT_IDIG_APP_ID
| Name | Description | |
|---|---|---|
| IG_ACCESS_TOKEN | — | |
| IG_ACCOUNT_ID | — | |
| IG_APP_ID | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableivanbbaev/instagram-mcp is public and reachablegithub.com/ivanbbaev/instagram-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/ivanbbaev/instagram-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model35 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubinstagram-mcp-ai — Instagram MCP Server
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.8.0(2026-10-13). 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 separates0.8.0from1.0.0. The MCP-registry entry, the MCPB bundle and the plugin-marketplace listing are separate submissions and are not live yet. The documents underdocs/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 34 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 the account's live stories.
- Comment moderation — list threads, reply, hide/unhide (reversible, preferred over delete) and delete; toggle whether a post accepts comments; 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-loginonly — 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_urlmust 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
enginesand 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) and the @mention lookups. |
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 and the
@mention lookups 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.
stdoutis the protocol channel; all diagnostics go tostderr. - Streamable HTTP — opt in with
IG_TRANSPORT=http. Loopback-bound (127.0.0.1:3000by default viaIG_HTTP_HOST/IG_HTTP_PORT; the olderIG_PORTstill works but is deprecated); setIG_HTTP_TOKENto require anAuthorization: Bearer <token>header (constant-time compared). LeavingIG_HTTP_TOKENunset 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 a token is refused outright, and a blank token is refused either way.
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: trueon the call, or setIG_WRITE_MODE=applyfor standing consent, to actually perform the write. - Destructive ops are double-gated. Irreversible actions (e.g.
instagram_delete_comment,instagram_delete_media) additionally requireIG_ALLOW_DESTRUCTIVE=true. - Journaled. Every applied write is appended to a local, append-only JSONL
journal (
~/.local/state/instagram-mcp-ai/writes.jsonl, orIG_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:
| Profile | IG_TOOL_PACKAGES=… |
Packages | Tools |
|---|---|---|---|
core (default) |
account, media, publishing, comments, insights |
the everyday read + publish + moderate set | 31 |
reader |
account, media, insights, comments, discovery |
read, insights and discovery — forced read-only (Path B for discovery) | 21 |
publisher |
account, media, publishing, comments |
publish and moderate | 27 |
all |
every package | the full surface | 35 |
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). instagram_token_status is
the one exception: it stays registered even when account is denied or left
out of an explicit list, so the token is always diagnosable in-band.
reader is read-only by name, not by arithmetic: its comments package
does contain write tools, so selecting it forces every package it resolves
to read-only, exactly as if IG_PACKAGES_READONLY had listed them all. No tool
that posts, hides, deletes or toggles anything is ever registered under reader
— that is why it exposes 17 tools and not 23. A hand-written package list is not
a read-only boundary; only the profile name (or IG_PACKAGES_READONLY) is.
Auth-path capability filtering runs on top: a tool restricted to one login path
is registered only when at least one configured profile is on that path, and the
per-call guard still rejects a mismatched account argument. So a deployment
with Path A credentials only drops the four fb-login-only tools
(instagram_list_linked_accounts plus the three discovery tools), while adding a
single Path B profile alongside brings them back.
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).
| Tool | Package | Auth paths | Access | Summary |
|---|---|---|---|---|
instagram_get_account |
account | both | Read | Fetch the profile of the operated Instagram professional account: username, display name, biography, website, profile-picture URL, and follower / following / media counts. |
instagram_get_accounts_overview |
account | both | Read | One report across the configured account profiles: for each profile the operator opted in with IG_FANOUT_PROFILES, its IG handle and follower / following / media counts, plus totals. |
instagram_list_linked_accounts |
account | fb-login | Read | Enumerate the Facebook Pages this token can act on and the Instagram business account linked to each (GET /me/accounts). |
instagram_token_status |
account | both | Read | Report the active credential: auth path (A = ig-login / B = fb-login), whether a token is configured, the resolved account ID, and — on Path B, via debug_token — validity, granted scopes, absolute expiry and days-left (with a refresh warning as the threshold nears). |
instagram_get_media |
media | both | Read | Fetch a single media object by id, including its carousel children (album items) under children. |
instagram_list_media |
media | both | Read | List the operated account's own media (feed posts, reels, albums), newest first, cursor-paginated. |
instagram_list_stories |
media | both | Read | List the operated account's live stories — only those still inside Instagram's 24-hour window, newest first, cursor-paginated. |
instagram_get_account_insights |
insights | both | Read | Account-level insights for the operated Instagram professional account (GET /{ig-id}/insights). |
instagram_get_audience_demographics |
insights | both | Read | Follower / engaged-audience demographics for the operated account (GET /{ig-id}/insights with metric_type=total_value). |
instagram_get_media_insights |
insights | both | Read | Insights for a single media object (GET /{media-id}/insights). |
instagram_get_online_followers |
insights | both | Read | Hourly distribution of when the account's followers are online (GET /{ig-id}/insights?metric=online_followers&period=lifetime). |
instagram_create_media_container |
publishing | both | Write | Phase 1 of publishing: create a media container that Instagram ingests from a public HTTPS URL. |
instagram_delete_media |
publishing | fb-login | Write | Permanently delete a published post, reel, story or whole carousel album (DELETE /{ig-media-id}). |
instagram_get_container_status |
publishing | both | Read | Read a media container's processing state: status_code is IN_PROGRESS, FINISHED, ERROR, EXPIRED, or PUBLISHED. |
instagram_get_publishing_limit |
publishing | both | Read | Report the account's content-publishing usage against its rolling-window quota. |
instagram_post_image |
publishing | both | Write | Publish a single feed image, or a 2–10 image carousel, in one call: create the container(s), wait for processing, then publish. |
instagram_post_reel |
publishing | both | Write | Publish a reel in one call: create the REELS container, wait for processing (reels can take a while), then publish. |
instagram_post_story |
publishing | both | Write | Publish a photo or video story in one call: create the STORIES container, wait for processing, then publish. |
instagram_publish_media |
publishing | both | Write | Phase 2 of publishing: publish a media container that has finished processing, returning the new media id. |
instagram_create_comment |
comments | both | Write | Post a new top-level comment on a media object (POST /{media-id}/comments). |
instagram_delete_comment |
comments | both | Write | Permanently delete a comment (DELETE /{comment-id}). |
instagram_get_comment |
comments | both | Read | Fetch a single comment by id, including its moderation state (hidden), parent/media context, and inline replies (repliesTruncated=true when Instagram returned only the first page of them; instagram_list_comment_replies reads the rest). |
instagram_get_mentioned_comment |
comments | fb-login | Read | Fetch a comment that @mentions the operated account, by its comment id (GET /{ig-id}?fields=mentioned_comment.comment_id(<id>){…}), with the id of the media it was made on. |
instagram_get_mentioned_media |
comments | fb-login | Read | Fetch a media object whose caption @mentions the operated account, by its media id (GET /{ig-id}?fields=mentioned_media.media_id(<id>){…}). |
instagram_hide_comment |
comments | both | Write | Hide a comment (POST /{comment-id}?hide=true) — reversible moderation, preferred over delete. |
instagram_list_comment_replies |
comments | both | Read | List the replies to one comment, cursor-paginated, in the order Instagram returns them. |
instagram_list_comments |
comments | both | Read | List the top-level comments on a media object, newest first, cursor-paginated, with threaded replies expanded inline under replies (repliesTruncated=true marks a thread Instagram cut at its first page of replies; instagram_list_comment_replies reads the rest). |
instagram_list_tagged_media |
comments | both | Read | List media the operated account has been TAGGED IN (the /tags edge), newest first, cursor-paginated. |
instagram_reply_to_comment |
comments | both | Write | Post a threaded reply under an existing comment (POST /{comment-id}/replies). |
instagram_set_comments_enabled |
comments | both | Write | Toggle whether a media object accepts new comments (POST /{media-id}?comment_enabled=true|false). |
instagram_unhide_comment |
comments | both | Write | Unhide a previously hidden comment (POST /{comment-id}?hide=false). |
instagram_discover_business |
discovery | fb-login | Read | Fetch another business/creator's PUBLIC profile and recent media by handle via GET /{ig-id}?fields=business_discovery.username(<handle>){followers_count,media_count,media{...}}. |
instagram_get_hashtag_media |
discovery | fb-login | Read | List PUBLIC media under a hashtag id via GET /{hashtag-id}/top_media or /{hashtag-id}/recent_media (choose via edge), which require the operated account's id as user_id. |
instagram_list_recently_searched_hashtags |
discovery | fb-login | Read | List the hashtags the operated account searched in the last 7 days via GET /{ig-id}/recently_searched_hashtags — Meta's own record of the 30-unique-hashtags per rolling 7 days budget that instagram_search_hashtag spends. |
instagram_search_hashtag |
discovery | fb-login | Read | Resolve a hashtag name to its Instagram hashtag id(s) via GET /ig_hashtag_search?user_id={ig-id}&q=<hashtag> (the returned id feeds instagram_get_hashtag_media). |
Prompts
Four MCP prompts package common workflows over the tools: instagram_weekly_report
(account and per-post insights for the last 1-30 days), instagram_caption_to_publish
(caption from a brief, then a previewed image, carousel or reel post),
instagram_comment_triage (classify comments, draft replies, propose hiding spam)
and instagram_discovery_research (hashtag and competitor research). They are
static templates: each one keeps the write gate (preview with apply: false,
apply: true only after you confirm) and treats Instagram content as untrusted
data. A prompt is listed only when every tool it uses is exposed under the active
profile, so the discovery prompt needs reader or all with a Path B profile,
and reader (read-only) hides the two prompts that write. Arguments and details:
docs/tools.md.
Resources
Four read-only MCP resources: instagram://account/profile (the operated
account's profile), instagram://media/recent (the 10 latest posts),
instagram://insights/account (account insights for the last 24 hours) and
instagram://reference/metrics (the metric names, periods and breakdowns the
insights tools accept). The first three read through the matching tool for the
default profile, with the same fencing of Instagram text and the same redaction,
and are listed only when that tool is exposed. Details:
docs/tools.md.
instagram-mcp-ai MCP questions
What tools does instagram-mcp-ai MCP provide?
It exposes 35 tools, including instagram_get_account, instagram_get_accounts_overview, instagram_list_linked_accounts, instagram_token_status, instagram_get_media.
Can I publish local files to Instagram using this server?
No, Instagram ingests media via public HTTPS URLs only. You must host your local files on a public server first.
What kind of Instagram accounts are supported?
The server is designed for Instagram professional accounts, which include both Business and Creator accounts.