Instagram MCP

Give your AI assistant your Instagram Insights. A local, read-only Model Context Protocol server for creators: your agent (Claude, ChatGPT desktop, Cursor, VS Code, …) can read your account's performance, trends, audience, posts, reels, stories and comments, straight from Meta's official Instagram API, and analyse them however you like.

"How did my Instagram do last month compared to the month before, and why?" "Which reels kept people watching longest this quarter, and what do they have in common?" "Who follows me vs who actually engages: age, gender, cities?" "When are my followers online? When should I post?" "Summarise the questions people ask in my comments." "Build a report of the last 28 days with charts."

It runs on your computer with your own Meta app and token. Your data goes from Meta to your machine to your AI app, and nowhere else. It never posts, comments or changes anything. It is the Instagram companion of youtube-studio-mcp.

What it can do

Full reference: docs/tools.md. Every tool is annotated read-only, every result states its exact date range and timezone, and anything Instagram can't provide is reported instead of invented. Lists can be saved as CSV or JSON (save_to).

Related MCP server: Instagram MCP Server

Requirements

• An Instagram professional account (Creator or Business).

• A free Meta developer account and a business portfolio (both take a minute to create).

• uv (brew install uv on macOS) and Python 3.11+ (uv installs it if needed). macOS, Linux and Windows are supported.

Quick start

uv tool install git+https://github.com/nelsonrogers/instagram-mcp
instagram-mcp auth      # paste the token from your Meta app (see below)
instagram-mcp check     # calls every tool against your account and prints the numbers

Then connect your MCP client.

One-time Meta app setup

About 15 minutes. Nothing here is ever published: the app stays in development mode (no privacy policy, domain or website needed), and your Instagram account is added to it as a tester. Meta's Standard Access covers accounts that have a role on the app, so no App Review is needed. The person who creates the app and the person who owns the Instagram account can be the same or different people.

Meta changed this in late 2026. New apps no longer offer API setup with Instagram login; they offer API setup with unified login (recommended by Meta, no Facebook Page needed, but the app must belong to a business portfolio) and API setup with Facebook login (needs a Facebook Page linked to the Instagram account). The steps below use unified login. The server accepts tokens from all three setups and tells them apart by itself. Meta's dashboard labels still move: whatever the screens say, the goal is a token for your account with instagram_basic and instagram_manage_insights (plus instagram_manage_comments for the comment tools).

1. Create the app

1. https://developers.facebook.com/apps → Create app.

2. App name: anything, e.g. My Instagram insights; contact email: yours.

3. Use case: Manage messaging & content on Instagram (the "Instagram API" use case).

4. Business portfolio: select your portfolio. The unified login setup only appears for apps that belong to one.

5. Finish with Create app. Leave it in Development mode; don't publish it.

2. Set up unified login and its permissions

In the app: Use cases → Manage messaging & content on Instagram → Customize.

1. In the left menu, open API setup with unified login (not API setup with Facebook login, which needs a Facebook Page linked to the account).

2. Open Permissions and features and add instagram_manage_insights. Check that instagram_basic and instagram_manage_insights both show Ready for testing.

3. The login configuration decides what the token can do, not Permissions and features. Meta's default configuration asks for instagram_basic, messaging, comments, publishing and ads permissions, but not instagram_manage_insights: a token generated with it can list posts but gets "(#10) Application does not have permission" on every insight. Open the configuration (on API setup with unified login, or Facebook Login for Business → Configurations), Edit permissions, tick instagram_manage_insights, keep instagram_basic and instagram_manage_comments, and untick what this server never uses (ads, publishing, messaging). If it offers a token expiration, choose Never. If it asks for a redirect URL, https://localhost/ will do.

3. Add the Instagram account as a tester

On API setup with unified login, section Generate access tokens:

1. Add account → your Instagram username. Meta invites the account as an Instagram Tester.

2. Accept the invite on a computer, at instagram.com, signed in as that account: Settings → Website permissions → Apps and websites → Tester invites → Accept (https://www.instagram.com/accounts/manage_access/ usually opens that page). The invite only appears after step 1, and only on the account that was invited.

4. Generate the token

Back on Generate access tokens, click Generate token next to the account (you may have to sign in to Instagram and approve the permissions), tick the box and copy the token. Meta shows it only once.

Don't paste the token into a chat, an email, a note, an issue or a file in a repository.

5. Save the token

instagram-mcp auth

Paste the token at the prompt (it is not shown on screen). The command recognises the kind of token, finds the Instagram account it can read, checks that insights work (and if not, lists the permissions Meta actually granted), and saves the token in ~/.config/instagram-mcp/tokens/default.json (readable only by your user, outside every repository). If it says Meta didn't list any account, pass the account's ID yourself: instagram-mcp auth --account 1784….

Their dashboards still show API setup with Instagram login, with the permissions instagram_business_basic, instagram_business_manage_insights and (for comments) instagram_business_manage_comments. The token from Generate access tokens → Generate token (it starts with IG) is saved the same way, with instagram-mcp auth. It lasts 60 days and the server renews it automatically (see Token lifetime). Looking up other accounts (get_instagram_public_account) isn't available with these tokens.

To sign in through the browser instead of copying a dashboard token:

instagram-mcp auth --oauth

This needs the Instagram app ID and Instagram app secret shown on the API setup with Instagram login page (not the Meta App ID). It asks for them (the secret is hidden; it is used once and never saved), or reads INSTAGRAM_MCP_APP_ID / INSTAGRAM_MCP_APP_SECRET. First register https://localhost/ under Business login settings → OAuth redirect URIs (or pass another registered URI with --redirect-uri). After you approve, the browser lands on that address, which doesn't load; paste the whole address back into the terminal.

Connect your MCP client

Use the full path printed by which instagram-mcp (usually ~/.local/bin/instagram-mcp).

ChatGPT desktop app: Settings → MCP servers → Add server → STDIO, name instagram, command: the full path to instagram-mcp. Save, then Restart. It is stored in ~/.codex/config.toml:

[mcp_servers.instagram]
command = "/Users/YOU/.local/bin/instagram-mcp"

Claude Desktop, Cursor and other clients:

{ "mcpServers": { "instagram": { "command": "/Users/YOU/.local/bin/instagram-mcp" } } }

Claude Code: claude mcp add instagram -- instagram-mcp.

To set the timezone (or any other setting), add an env block, e.g. "env": { "INSTAGRAM_MCP_TIMEZONE": "Europe/Paris" }.

The server also offers ready-made prompts (Instagram check-up, Post deep dive, Audience portrait, Benchmark accounts) in clients that show MCP prompts.

Token lifetime

instagram-mcp status shows the account, the API it uses and when the token expires.

• Unified login tokens (they start with EAA, host graph.facebook.com) belong to the business portfolio, not to a person. Their lifetime is set in the app's configuration, often never. They can't be renewed through the API: if one expires or stops working, generate a new one (step 4) and run instagram-mcp auth again.

• Instagram Login tokens (older apps; they start with IG) last 60 days. The server renews them automatically whenever it is used and the token is about 10 days old or more; instagram-mcp refresh renews it now. After more than 60 days without use, generate a new token and run instagram-mcp auth.

CLI

instagram-mcp [serve]      run the MCP server over stdio (what MCP clients launch)
instagram-mcp auth         save a token from the Meta App Dashboard (--token-stdin, --account, --oauth)
instagram-mcp status       account, token expiry, settings
instagram-mcp check        call every tool against your account and print the results
instagram-mcp report       write a full report as JSON (--period, --start-date, --end-date, --thumbnails, --out)
instagram-mcp refresh      renew an Instagram Login token now
instagram-mcp logout       delete the stored token

Configuration

All optional, as environment variables (also usable in an MCP client's env block).

Good to know

• Periods. Named periods (last_7_days … last_365_days, this_month, last_month, this_year, last_year, all_available) end yesterday; custom dates can go back two years, Meta's limit. Meta's numbers can still change for 48 hours.

• Reach over long periods. Meta reads at most 30 days per request. Totals like views and likes are added up over longer periods, but reach and accounts engaged count unique accounts and can't be, so they are null beyond 29 days (use weekly trends instead).

• Post metrics are lifetime totals, since publication. Meta doesn't give follows or profile visits for reels, and lists stories only during their 24 hours.

• Audience. Demographics need at least 100 followers (or engaged accounts) and cover the top 45 cities and countries. app_share_pct and share_of_known_pct reproduce the Instagram app's own charts, which leave out followers of unknown gender.

• Not available through Meta's API: hashtag search (needs Meta App Review), expired stories, and collaboration posts owned by another account.

How the numbers are computed, and what was checked against a real account: docs/decisions.md.

Privacy & security

• Read-only: the server only calls GET endpoints for profile fields, insights, media, comments and tags, and every tool is annotated read-only. If the token carries more permissions (messaging, publishing), they are never used.

• Runs locally over stdio, with no telemetry or third-party service.

• The token is stored outside any repository with owner-only permissions (0600 in a 0700 folder). It never appears in logs, error messages or tool results.

• Comment text and other people's captions are returned to your agent as data: they could contain instructions aimed at AI agents, so review what your agent proposes.

See SECURITY.md to report a vulnerability.

Troubleshooting

1. instagram-mcp check calls every tool and prints what came back, with warnings for empty answers.

2. "(#10) Application does not have permission": the token lacks instagram_manage_insights (setup step 2.3); generate a new token. For comments, the same with instagram_manage_comments.

3. Sign-in problems: instagram-mcp status, then instagram-mcp auth with a new token.

4. Numbers differ slightly from the app: Meta's data can lag up to 48 hours, and the app may use another timezone; set INSTAGRAM_MCP_TIMEZONE.

Development

git clone https://github.com/nelsonrogers/instagram-mcp && cd instagram-mcp
uv sync
uv run pytest                     # against a rule-checking fake of the Graph API, no account needed
uv run ruff check . && uv run ruff format --check . && uv run mypy
uv run python scripts/generate_docs.py   # after changing a tool or the report

cli.py ─► server.py ─► tools/ account · analytics · content · discovery · report  (all read-only)
          prompts.py   MCP prompt templates
          selfcheck.py `instagram-mcp check`: every tool through an in-process MCP client
insights.py    Meta's API → snake_case: totals, breakdowns, demographics, posts
periods.py     named periods, timezone, 29-day request windows, buckets
context.py     shared arguments, errors, save_to
thumbnails.py  160 px WebP data URIs
instagram.py   Graph client: versioned GETs, error translation, retries, cursors
auth.py        token store (0600), both token kinds, auto-refresh, OAuth
config.py      INSTAGRAM_MCP_* settings

See CONTRIBUTING.md. Changes are listed in CHANGELOG.md.

License

MIT. Not affiliated with, endorsed or sponsored by Meta or Instagram. Instagram is a trademark of Meta Platforms, Inc.