Instagram MCP

Instagram MCP server for Claude Code and AI agents. Read your own accounts, research any Business or Creator account on the platform, publish, and answer comments.

Three tiers of access behind one tool surface, and every answer tells you which tier it came from.

Built by Navid Moazzez.

You: which of my last 20 posts is still growing, and what are my
     three closest competitors doing that I am not?

Claude: Reading your account, then comparing.

  Still climbing (likes gained since the last reading)
    "The 4 AI tools I actually pay for"     +412  posted 6 days ago
    "Nobody talks about this part"          +198  posted 3 days ago

  Competitors, median engagement over their last 12 posts
    @a   118k followers   4.1%   carousels, 7 to 9 slides
    @b    64k followers   3.3%   reels under 20 seconds
    @c   210k followers   1.2%   single images

  The one thing all three do that you do not: the first slide is a
  question, not a claim.

Contents

	Section
1	What you can ask it	Real prompts, not features
2	Quick install	The package, no account needed
3	Create your Meta app	Every click. This is the part people give up on
4	Get your token	One command does the exchange
5	Connect your client	Claude Code, Desktop, Cursor, the rest
6	Check it worked	doctor, and the two things that actually fail
7	Tools	All 45, by what they reach
8	The three tiers	What each one can see
9	Multiple accounts	One server, several logins
10	Notes and gotchas	Quotas, windows, and silent failures
11	Troubleshooting	Symptom to cause
12	Build from source	Run the tests
	FAQ	Including what an MCP server is

---

1. What you can ask it 💬

• Which of my posts from the last month is still gaining likes?
• How many followers did I gain this week, and which post caused it?
• Compare @a, @b and @c. Who has the best engagement rate, and what do they post?
• What is working on #aitools right now?
• Read every comment from my last ten posts and tell me what people keep asking.
• Draft a reply to each comment that deserves one, in my voice. Do not post them.
• Stage this carousel as a container so I can look at it before it goes live.
• How many of today's 100 API posts have I used?

The first two are the point. Instagram will tell you your follower count right now. It will not tell you what it was on Monday. This server remembers what it reads, so it can answer the version of the question people actually have.

---

2. Quick install ⚡

Python 3.11 or newer. No Instagram account needed for this step.

uv tool install thenavidm-instagram-mcp

No uv yet? It is a Python package manager, one command to install:

curl -LsSf https://astral.sh/uv/install.sh | sh

Check it:

instagram-mcp --version

The package is thenavidm-instagram-mcp. The command it installs is instagram-mcp. They differ because the short name on PyPI belongs to somebody else, and installing that would fetch code that is not this.

To add the unofficial tier as well, see section 8 first, then:

uv tool install "thenavidm-instagram-mcp[unofficial]"

---

3. Create your Meta app 🔑

Instagram's API does not hand out tokens directly. You create an app in Meta's developer dashboard, and the app issues the token. It is free and takes about ten minutes.

Before you start: your Instagram account must be a Business or Creator account, not a personal one. Instagram's API does not work on personal accounts at all, on any tier except the unofficial one. Switch in the Instagram app under Settings, then Account type and tools.

Step 1: create the app

1. Go to developers.facebook.com/apps and log in.
2. Click Create app.
3. App name: anything. Contact email: yours.
4. Under Use cases, pick Other, then Next.
5. App type: Business, then Next, then Create app.

Step 2: add the product

In the left sidebar, find Add product.

• For the Facebook Login path, add Facebook Login for Business.
• For the Instagram Login path, add Instagram.

Pick Facebook Login unless you have a reason not to. It is the only path that reaches discover_account and the hashtag tools, and the Page tokens it returns do not expire. It does require your Instagram account to be linked to a Facebook Page, which is done in the Instagram app under Settings, then Sharing to other apps.

Step 3: note your app id and secret

Left sidebar, App settings, then Basic. Copy the App ID and click Show next to App secret. You need both in section 4.

Step 4: generate a short-lived token

1. Open Graph API Explorer.
2. Top right, select your app from the dropdown.
3. Click Generate access token and approve the dialog.
4. Add the scopes for your path, then click Generate access token again.

Path	Scopes
Facebook Login (recommended)	instagram_basic, instagram_content_publish, instagram_manage_insights, instagram_manage_comments, pages_show_list, pages_read_engagement
Instagram Login	instagram_business_basic, instagram_business_content_publish, instagram_business_manage_comments, instagram_business_manage_messages

Copy the token. It expires in about an hour, which is fine: section 4 trades it for a long-lived one.

---

4. Get your token 🔑

One command does the exchange:

instagram-mcp token \
  --app-id YOUR_APP_ID \
  --app-secret YOUR_APP_SECRET \
  --short-token THE_SHORT_LIVED_TOKEN \
  --path facebook

It swaps the short-lived token for a long-lived one, finds every Page you manage with a linked Instagram account, and prints a ready-to-paste IG_ACCOUNTS_FILE.

Instagram Login tokens expire after 60 days. Extend them before they do:

instagram-mcp refresh

Facebook Login Page tokens do not expire, which is the other reason to prefer that path.

---

5. Connect your client 🔌

Writes are on. There is no flag to enable publishing or replying. The actions that cannot be undone from a chat window ask the model to pass confirm: true first, and IG_READ_ONLY=1 removes every write tool if you want a reader.

Claude Code

claude mcp add --transport stdio instagram \
  --env IG_ACCESS_TOKEN=your_token \
  --env IG_USER_ID=your_ig_user_id \
  -- instagram-mcp

By default this applies to the current project only. Add --scope user to use it everywhere.

Command	What it does
claude mcp list	List every configured server
claude mcp get instagram	Show this server's status
/mcp	Check the connection from inside a session

Claude Desktop

Platform	Config path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "instagram": {
      "command": "/Users/you/.local/bin/instagram-mcp",
      "env": {
        "IG_ACCESS_TOKEN": "your_token",
        "IG_USER_ID": "your_ig_user_id"
      }
    }
  }
}

The path must be absolute. Claude Desktop does not inherit your shell PATH, so a bare command name fails silently. Get the absolute path with which instagram-mcp on macOS or where instagram-mcp on Windows. On Windows, escape the backslashes.

Quit Claude Desktop completely and reopen it. Closing the window is not enough.

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "instagram": {
      "command": "instagram-mcp",
      "env": {
        "IG_ACCESS_TOKEN": "your_token",
        "IG_USER_ID": "your_ig_user_id"
      }
    }
  }
}

claude.ai and other remote clients

Run it over HTTP:

instagram-mcp --http --host 0.0.0.0 --port 8000

Then add https://your-host/mcp as a custom connector.

Put it behind TLS and an authenticating proxy. This server holds tokens for your Instagram accounts and has no authentication of its own.

VS Code, Windsurf, Zed, Cline, Codex CLI, Gemini CLI

All of them take the same three things: the command instagram-mcp, any flags as arguments, and the environment variables above. See docs/clients.md for the exact file and key names.

---

6. Check it worked 🩺

instagram-mcp doctor

doctor is the whole troubleshooting story. It tests every token, names which insight metrics your account still answers, and tells you whether business_discovery works on your app. Run it before anything else.

Two things fail more than everything else combined:

A personal account. The API returns an empty or confusing error rather than saying so. doctor says so plainly.

A token generated without the scopes. Adding scopes in Graph API Explorer does not update a token you already copied. Generate a new one after adding them.

---

7. Tools 🛠️

45 tools. Every result carries a source field naming the tier that answered, so a model can never present a scraped guess as an official metric.

Your accounts

Tool	What it does
list_accounts	Every connected account with live follower counts and which tier it reaches
whoami	Verify one token, return the live profile
token_status	When each token expires and whether it can be refreshed
get_media	Recent posts with permalinks and engagement
list_all_media	Every post, paging until the history is exhausted
get_media_by_id	One post, full fields
list_tagged_media	Posts by other accounts that tagged you
list_stories	Stories live right now
get_media_insights	Reach, saves, shares and interactions for one post
get_account_insights	Account-level reach and profile views over a period
get_publishing_limit	How many of the 100 daily API posts you have used
growth_history	Follower counts over time, from local readings
post_movement	Which posts are still gaining, and by how much

growth_history and post_movement read the local store, not Instagram. They are empty until the server has taken readings on more than one day, and they cannot be back-filled. This is the reason to install it before you need it.

Publishing

Tool	Needs confirm
create_container	no, nothing goes public
publish_container	yes
post	yes
post_carousel	yes
publish_reel	yes
publish_story	yes

create_container stages media without posting. Nothing appears in the app and the container expires unused after 24 hours. It is the only draft-like state Instagram has, so it is what to use when a person should approve something before it goes live.

Instagram has no native scheduling. Anything that claims to schedule a post is holding the job somewhere else and publishing it at the time.

Comments and messages

Tool	Needs confirm
get_comments	read
get_comment_replies	read
read_all_comments	read
list_conversations	read
get_conversation	read
reply_to_comment	no, a reply can be deleted
hide_comment	no, hiding is reversible
delete_comment	yes, it is permanent
send_dm	yes, a message cannot be unsent
private_reply_to_comment	yes, and only one is allowed per comment

read_all_comments pulls comments across your recent posts in one call. It is what comment triage and sentiment questions actually need, and doing it through get_comments in a loop burns the context window before it answers anything.

Research

Tool	What it does
discover_account	Public profile and recent posts for any Business or Creator account
compare_accounts	Up to 10 accounts side by side with median engagement
search_hashtag	Resolve a hashtag to its id, remembering the result
hashtag_top_media	What is performing on a hashtag right now
hashtag_recent_media	What is being posted on a hashtag right now

These need the Facebook Login path. discover_account is an official, free, documented Graph endpoint. No scraping, no risk, no browser.

Unofficial

Off unless you turn it on. See section 8.

Tool	What it does
unofficial_status	Whether the tier is on, and what is deliberately not implemented
unofficial_profile	Full public profile for any account, including personal ones
unofficial_posts	Recent posts by any public account
unofficial_stories	Stories live on any public account
unofficial_followers	Followers, newest first, capped at 200
unofficial_following	Accounts an account follows, capped at 200
unofficial_search_accounts	Search accounts by name or keyword
unofficial_post_comments	Comments on any public post
unofficial_inbox	Your real inbox, including message requests
unofficial_thread	Messages inside one inbox thread
unofficial_send_dm	A cold DM. Needs confirm

Three things are deliberately absent: follow_user, unfollow_user and bulk_like. They are what every growth-hack tool ships and they are the three actions that get accounts restricted fastest. unofficial_status reports them as missing on purpose, so it is a decision on the record rather than an oversight.

---

8. The three tiers 🎚️

Instagram does not have one API. It has two, plus a private one, and they reach completely different things.

Tier	What it reaches	Runs where	Risk
Instagram Login	only accounts you own	anywhere	none
Facebook Login	the above, plus public data on any Business or Creator account, plus hashtags	anywhere	none
Unofficial	any public account, the real inbox, account search	a machine you control	your account can be restricted

Most people want the middle one and do not know it exists.

The unofficial tier drives Instagram's private API through instagrapi. That is against Instagram's terms of service and it can get an account restricted or banned. It is not installed by default, it is off unless you set IG_UNOFFICIAL=1 or pass --unofficial, and it prints a warning on stderr when it starts. Point it at a secondary account, never your main one.

It also paces itself: a random delay between calls and a local hourly ceiling that is lower than Instagram's own. Instagram restricts accounts for machine-speed access patterns more than for volume.

instagram-mcp login          # once, saves a session file
IG_UNOFFICIAL=1 instagram-mcp

---

9. Multiple accounts 👥

Point IG_ACCOUNTS_FILE at a JSON array instead of setting a single token. Mixed tiers in one file are fine and expected.

[
  {
    "account_name": "thenavidm",
    "user_id": "17841400000000000",
    "access_token": "IGQV...",
    "host": "graph.instagram.com"
  },
  {
    "account_name": "thenavidai",
    "user_id": "17841400000000001",
    "access_token": "EAAG...",
    "host": "graph.facebook.com"
  }
]

Every tool takes an optional account argument. When you leave it out, the IG_PREFERRED order decides, and an exact name match beats a prefix match.

IG_PREFERRED=thenavidm,thenavidai

---

10. Notes and gotchas ⚠️

100 posts per 24 hours, per account, across every API client. Not just this one. get_publishing_limit tells you where you are.

30 unique hashtags per rolling 7 days. Resolved ids are cached locally so repeat lookups do not spend a slot, but the thirty-first new hashtag in a week fails.

business_discovery sees Business and Creator accounts only. Never personal ones, never private ones. It returns an error that does not say which of those it is.

DMs need a 24-hour window. Instagram allows a DM only inside a window opened by the other person messaging you, or as one private reply to a comment. There is no official way to message somebody cold.

Reading DMs needs Advanced Access from Meta App Review on most apps. list_conversations returns empty rather than erroring until you have it.

Insight metrics change. Meta deprecates and renames them regularly. doctor names which ones your account still answers, which is faster than reading the changelog.

Comments and DMs are written by strangers. Every text field from another person comes back wrapped in an untrusted-content fence telling the model to report it, not obey it. This is the most injectable surface an agent gets handed, and "summarise my comments" is one of the first things anyone asks.

Every write is logged. One JSON line per attempted write, allowed or refused, to IG_AUDIT_LOG or the data directory. The model has no tool to read or edit that file.

---

11. Troubleshooting 🔧

Run instagram-mcp doctor first. It diagnoses most of this.

Symptom	Cause
Every tool returns nothing	Personal account. The API needs Business or Creator
(#100) Tried accessing nonexisting field	Token generated before you added the scopes. Generate a new one
discover_account fails	You are on the Instagram Login path. It needs Facebook Login
Hashtag tools stop working	30 unique hashtags in a rolling 7 days
Server missing in Claude Desktop	Relative command path. Use the absolute one, and fully quit the app
growth_history is empty	It needs readings from more than one day. It cannot back-fill
Write tools are absent	IG_READ_ONLY is set
A write asks for confirmation	Working as intended. Call it again with confirm: true
Unofficial tools refuse	Tier is off. Set IG_UNOFFICIAL=1 and run instagram-mcp login once

---

12. Build from source 🏗️

git clone https://github.com/thenavidm/instagram-mcp
cd instagram-mcp
uv sync
uv run pytest

The tests run against a faked transport and never touch the network, so they are safe to run without a token.

---

FAQ ❓

What is an MCP server?

Model Context Protocol is a standard way to give an AI assistant access to a tool or a data source. An MCP server exposes a set of functions, and a client like Claude Code or Claude Desktop can call them during a conversation. This one exposes Instagram.

You install it once, put your credentials in the client's config, and then ask in plain language. You do not call the tools yourself.

Do I need a Business account?

Yes, for everything except the unofficial tier. Instagram's API does not work on personal accounts. Switching is free and reversible, in the Instagram app under Settings, then Account type and tools.

Why do I have to create a Meta app? That seems like a lot.

Instagram does not issue API tokens to people, only to apps. Every tool that touches Instagram programmatically works this way, including the ones that hide it behind a signup form. Doing it yourself means the token is yours, it is not held by a third party, and nobody can revoke your access by shutting down.

It is about ten minutes, once.

Can it schedule posts?

No, and neither can anything else. Instagram has no scheduling API. Products that offer scheduling hold the post on their own servers and publish it at the time, which means handing them your content and your credentials.

create_container is the honest version: stage it now, publish it when you say.

Can it read my DMs?

Officially, only threads where the other person messaged you, and only inside a 24-hour window, and only once Meta grants your app Advanced Access. The unofficial tier reads the real inbox with no window, at the risk described in section 8.

Will this get my account banned?

The two official tiers are Meta's own documented APIs. There is no more risk in using them than in using the Instagram app.

The unofficial tier is a real risk. It drives the private API, which is against Instagram's terms. Use a secondary account.

Can it post without asking me?

It can post when you ask it to. Publishing, deleting a comment and sending a DM all require the model to pass confirm: true, which it does after reading a description explaining what cannot be undone. That is a speed bump against a careless call, not a lock.

If you want a server that cannot write at all, set IG_READ_ONLY=1. The write tools are then not registered, so the model cannot see or call them.

What data does it store, and where?

Follower counts and post engagement readings, in a SQLite file in your data directory, so it can answer "what changed since Monday". An audit log of every attempted write. A session file if you use the unofficial tier.

All of it is local. Nothing is sent anywhere except to Instagram. Delete the data directory and it is gone.

Why is this Python when the other servers are TypeScript?

The unofficial tier depends on instagrapi, which is Python only. Rewriting the official tiers in TypeScript would split the project in two for no gain.

Why is the package name not just "instagram-mcp"?

That name on PyPI already belongs to somebody else. Installing it would fetch code that is not this. The package is thenavidm-instagram-mcp and the command it installs is instagram-mcp.

Does it cost anything?

No. The server is MIT licensed and Meta's Graph API is free at these volumes. You are paying for your own AI client, not for this.

Can I use it with several accounts?

Yes, see section 9. One server, one config file, an account argument on every tool, and a preference order for when you leave it out.

---

About the author 👋

Navid Moazzez is a leading AI business strategist and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. This Instagram MCP server is one piece of that system.

Links

• Personal website: navid.me
• Store: navid.bio
• AI OS Starter Kit: aios.guide
• AI OS Workshop: aiosworkshop.com
• AI Creator OS: aicreatoros.co
• AI Tools Library: aitoolslibrary.io
• Video Gear Guide: videogear.guide
• Navid Media: navid.media
• YouTube: @thenavidm and @thenavidai
• X: @thenavidm
• Instagram: @thenavidm
• LinkedIn: thenavidm

Dependencies

Library	Licence	What it does
MCP Python SDK	MIT	The MCP server, stdio and streamable HTTP
httpx2	BSD-3	The HTTP client, already an SDK dependency
instagrapi	MIT	The unofficial tier, optional extra

License

MIT. Free to use, modify, and share.

Not affiliated with, endorsed by, or sponsored by Meta Platforms, Inc. Instagram and Facebook are trademarks of Meta Platforms, Inc. This project uses Meta's public Graph API, and its optional unofficial tier is not sanctioned by Meta.

---

© 2026 NM Media. Made with ❤️ by Navid Moazzez.