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

Related MCP server: Instagram MCP Server

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.

git clone https://github.com/navidmoazzez/instagram-mcp
uv tool install ./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

Once published:

uv tool install thenavidm-instagram-mcp

The package name and the command differ on purpose. The short name on PyPI belongs to somebody else, so installing that would fetch code that is not this. The installed command is instagram-mcp either way.

For the unofficial tier as well, read section 8 first, then add the extra:

uv tool install "./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/creation and log in.

2. App details. Enter your app's name and a contact email address, then Next. The name is not shown to anyone but you at this stage.

3. Use cases. This screen is a list of what the app is allowed to do. Tick Manage messaging and content on Instagram, then Next.

   That one name covers reading posts, insights, comments, DMs and publishing. There is no separate "Instagram API" option, which is what people look for and do not find.

   The other names on this screen belong to different products:

   Use case	What it is for
   Manage messaging and content on Instagram	this server, tick it
   Access Threads API	Threads, see below
   Manage everything on your Page	Facebook Pages

   You can tick more than one. Incompatible combinations are greyed out, so if an option will not tick, it conflicts with something already selected.

4. Business. Choose A verified business portfolio, An unverified business portfolio, or I don't want to connect a business portfolio yet. The last option is fine to start with.

5. Requirements. Review whatever it lists, then Next.

6. Overview. Check the details, then Go to dashboard.

Step 2: add the permissions

1. Click Dashboard in the left menu.

2. Select the use case to customise.

3. Click Add all required permissions.

You can also reach these under Permissions and features in the left menu, to add or remove individual ones.

Step 3: pick your login path

Two setups, and they reach different things. This is the decision that matters most, so read the table in section 8 before choosing.

Instagram Login is the simpler one. In the left menu, API setup with Instagram login. It reaches only accounts you own.

Facebook Login reaches more. It is the only path that gets discover_account and the hashtag tools, and the Page tokens it returns do not expire. It needs your Instagram account linked to a Facebook Page.

Step 4: generate a token

In the use case's Generate access tokens section, click Add account and approve the dialog. Meta returns a short-lived token.

For the Facebook Login path you can also use Graph API Explorer: select your app, add the permissions above, then generate.

Copy the token. It is short-lived, 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.

Underneath, the Instagram Login exchange is this:

GET https://graph.instagram.com/access_token
  ?grant_type=ig_exchange_token
  &client_secret=YOUR_APP_SECRET
  &access_token=THE_SHORT_LIVED_TOKEN

That returns a token good for 60 days. The request carries your app secret, so it belongs in server-side code only. Never in a browser, never in anything shipped to a device, never committed.

Extend it before it expires:

instagram-mcp refresh

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

One app also covers Threads and Facebook

You do not create a second app for those. The same app carries several use cases, with one app id, one secret and one Roles list, so a tester you add once can use all of them.

What is not shared is the token. Each product mints its own against its own host, so an Instagram token does not work on Threads.

If you want either, tick its use case back in step 1 and then follow that server's own setup, which is written up in its repo rather than duplicated here:

Adding a use case later is fine. It does not invalidate the token you already have.

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.

Claude Desktop

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

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

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

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

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

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.

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.

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

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.

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 🚧

• Publishing needs public HTTPS URLs. Meta fetches the media server-side, so a local file path will not work. Host the image or video somewhere reachable first.

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

• business_discovery sees Business and Creator accounts only. Never personal, never private. The error does not say which of those it hit.

• DMs need a 24-hour window. Instagram allows a DM only inside a window the other person opened by 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 the ones your account still answers, which is faster than reading the changelog.

• Errors come back as a structured result, not an exception, carrying the Graph error's code, subcode and fbtrace_id. That is Instagram's error, not a bug in this server.

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

12. FAQ ❓

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.

You need one 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.

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.

It cannot, 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.

It reads only the threads where the other person messaged you, 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.

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.

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.

It stores 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.

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.

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.

It costs nothing. 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.

You can connect as many as you like, as section 9 covers. One server, one config file, an account argument on every tool, and a preference order for when you leave it out.

Questions

Run into a problem or have a question? Open an issue and I will help.

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

• Navid Media: navid.media

• YouTube: @thenavidm and @thenavidai

• X: @thenavidm

• Instagram: @thenavidm

• LinkedIn: thenavidm

If this is useful, star the repo and come say hi on X.

Dependencies

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.