Skip to main content
Glama

instagram-mcp

An MCP server that lets AI agents use an Instagram account through a real, logged-in Chrome browser. No browser extension, no paid subscription, and it runs on a server with Docker.

Node.js 20+ TypeScript MCP Docker Tools Status License: MIT

Quick start · Tools · How it works · Staying safe · Contributing

What is this?

instagram-mcp gives an AI agent such as Claude Code access to one Instagram account. The agent can read profiles and posts, reply to DMs, comment, like and follow, analyze followers, and find potential customers and keep them in a lead list.

Once the agent is connected, you can ask it things like:

Find coffee shops in Brooklyn that still take orders over WhatsApp, score them, and show me the top-priority ones.

The agent then calls lead_discover, lead_enrich, and lead_list on its own.

Related MCP server: Instagram MCP Server

Why not the official Instagram API?

The official Instagram Graph API only works for business accounts linked to a Facebook Page. It can't freely read other people's profiles or search for leads, and DM access requires Meta's app review.

instagram-mcp works the way you do in a browser. Every request is sent from an instagram.com page that is already logged in, so you get the same data you would see on the web.

Quick start

You need Node.js 20 or newer and Google Chrome.

git clone https://github.com/wirnat/instagram-mcp.git
cd instagram-mcp
npm install
npm run build
node dist/index.js login

login opens a Chrome window. Log in to Instagram there. The window closes by itself once you are logged in, and the server never reads your password.

Start the server and connect Claude Code:

node dist/index.js serve --http
claude mcp add --transport http instagram http://127.0.0.1:48300/mcp

To check the connection, ask the agent "Which Instagram account is logged in?". It will call account_info.

NOTE

Only one process can use the Chrome profile at a time. Run a single server in HTTP mode and point all your agents at that address.

login                 Open a Chrome window to log in to Instagram (once per machine)
serve [--http]        Run the MCP server. stdio by default; --http serves http://127.0.0.1:48300/mcp
status                Check whether the Instagram session is still logged in
tools                 List the tools
call <tool> [json]    Call one tool (through the HTTP server if one is running)
probe <url> [ms]      Open an Instagram page and record the GraphQL queries it loads

Running on a server with Docker

The base image is 3.6 GB, so check your free disk space first.

df -h
echo "INSTAGRAM_MCP_TOKEN=$(openssl rand -hex 24)" > .env
docker compose build

Log in once through noVNC, which shows the container's Chromium window in your browser:

docker compose run --rm -p 127.0.0.1:6080:6080 instagram-mcp login

From your laptop, open an SSH tunnel to port 6080 on the server, go to http://localhost:6080/vnc.html, and log in to Instagram there. The container stops once the login succeeds.

docker compose up -d

The server listens on 127.0.0.1:48300 on the host. Agents connect with the header Authorization: Bearer <INSTAGRAM_MCP_TOKEN>. If your agents run on another machine, put a TLS reverse proxy in front of it.

Tools

There are 67 tools. ✅ means the tool was tested against real Instagram on November 14, 2026 with a test account. 🧪 means the code exists but hasn't been tested yet, so don't rely on it.

Group

Tools

Account and reading

✅ account_info ig_fetch_profile ig_fetch_posts ig_fetch_post ig_search ig_hashtag_posts ig_fetch_stories ig_fetch_saved ig_fetch_tagged location_search

DMs

✅ dm_list dm_read dm_send dm_requests dm_mark_seen

Comments

✅ comments_list comment_add comment_reply comment_like comment_delete

Actions

✅ ig_action (like, unlike, follow, unfollow) ig_block (block only) · 🧪 follower_remove

Notifications

✅ notifications_list follow_requests_list events_check

Followers

✅ peers_scan peers_report peers_export antibot_scan antibot_report · 🧪 unfollowers_scan unfollowers_report story_viewers

Insights and downloads

✅ insights_collect insights_report downloads_start downloads_status

Leads

✅ lead_discover lead_from_location lead_from_followers lead_from_engagers lead_similar lead_enrich link_inspect lead_list lead_update lead_export lead_config

Publishing

✅ draft_create draft_list and the other draft tools (local storage only) · 🧪 draft_publish ig_post_edit ig_post_delete

Profile

🧪 profile_update note_set

Jobs

✅ jobs_status

Run node dist/index.js tools for the full list with parameters.

Finding leads

  1. Call lead_discover with a keyword and a city, for example "coffee shop" and "Brooklyn". Candidates are saved as unscored.

  2. Call lead_enrich with pending to fetch each profile and give it priority A, B, or C. Add deep to also open the links in the bio, and activity to check whether the account still posts.

  3. Use lead_list to pick who to contact. Sending a DM with dm_send moves the lead's status to contacted.

Out of the box the scoring is generic: it looks at follower count, contact details, and booking links. You can teach it what your ideal customer looks like with lead_config, which takes business types, cities, competitor booking apps, and a default phone country code. examples/lead-config.salon-id.json is a full example for salons and barbershops in Indonesia, and you can load it with lead_config and preset: "salon-id".

How it works

flowchart LR
    A[AI agent<br>Claude Code] -->|MCP stdio / HTTP| B[instagram-mcp]
    B --> C[Paced queue<br>3.5 to 8 s apart]
    C --> D[Chrome with a<br>logged-in profile]
    D -->|Same GraphQL<br>as the web app| E[instagram.com]

The server runs Chrome with its own profile in ~/.instagram-mcp/profile. Every request is sent from inside an instagram.com page, with that browser's cookies and headers.

Instagram's web app gets almost all of its data through GraphQL, and the server calls the same queries. Query IDs (doc_id) are not hard-coded. The server reads them from the JavaScript that Instagram loads, so they stay current when Instagram ships a new version.

Some queries are only loaded on specific pages, such as the DM inbox. For those, the server opens the page once, records the request the web app sends, and caches it in ~/.instagram-mcp/data/gql-learned.json.

Staying safe

WARNING

Automating an account breaks Instagram's terms of use, and the account can be restricted or banned. Keep the volume low, and test with an account you can afford to lose.

The server already limits itself:

  • All requests go through one queue with a random 3.5 to 8 second gap.

  • Default daily limits are 15 DMs to new people, 150 likes, 60 follows, and 60 comments.

  • If Instagram asks for verification or blocks an action, the server stops sending actions for a few hours.

  • If the session gets logged out, the server stops sending requests until you log in again.

Two more rules come from things that went wrong during testing:

  1. Don't run many searches back to back. About six searches within a few minutes got a "Try Again Later" response. Leave a few minutes between batches.

  2. Never call an endpoint the web app doesn't use. A single request to a guessed API path got the session logged out. Use probe to see what the web app sends and copy it exactly.

Configuration

Variable

Default

Meaning

INSTAGRAM_MCP_HOME

~/.instagram-mcp

Folder for the Chrome profile, data, and downloads

INSTAGRAM_MCP_PORT

48300

HTTP port

INSTAGRAM_MCP_HOST

127.0.0.1

Address to listen on

INSTAGRAM_MCP_TOKEN

empty

Bearer token, required when the host is not 127.0.0.1

INSTAGRAM_MCP_HEADLESS

false

Run Chrome without a window

INSTAGRAM_MCP_CHROME_CHANNEL

chrome

Leave empty to use Playwright's bundled Chromium

INSTAGRAM_MCP_MIN_GAP_MS, INSTAGRAM_MCP_MAX_GAP_MS

3500, 8000

Gap between requests

INSTAGRAM_MCP_LIMIT_COLD_DM, _LIKE, _FOLLOW, _COMMENT

15, 150, 60, 60

Daily limits

Not supported yet

  • Accepting or declining message requests.

  • Unblocking an account. Use the Instagram app for now.

  • Music, story stickers, and links in stories.

  • Account search returns about 5 results per keyword, which is a limit of Instagram's web search. For more, use ig_hashtag_posts or lead_discover.

Contributing

The most useful contributions right now are testing the 🧪 tools and adding tools for the features above. Read Staying safe first, and use a test account, not a business account.

Setup

npm install
npm test                                    # build and unit tests
node scripts/smoke.mjs                      # MCP over stdio, without touching Instagram
node scripts/smoke-http.mjs <url> <token>   # HTTP mode and bearer token

Adding a tool

Each tool is registered with defineTool in one of the files in src/tools/:

defineTool({
  name: 'dm_mark_seen',
  description: 'Mark a DM thread as seen up to its latest incoming message.',
  params: [{ name: 'thread_id', type: 'string', description: 'Thread id from dm_list.', required: true }],
  risk: 'write', // read, write, or action
  handler: async ({ thread_id }, ig) => {
    // call ig.gql(...) with the same query the web app uses
  },
})

To find the query the web app uses, start the server with INSTAGRAM_MCP_DEBUG=1 and run:

node dist/index.js probe /direct/inbox/ 8000          # open a page and record the queries it sends
node dist/index.js raw OP PolarisPostRootQuery '{}'    # show a query's doc_id and variables
python3 scripts/call.py ig_fetch_profile '{"username":"natgeo"}'

The web app sends some queries to /graphql/query and others to /api/graphql. All mutations and DM queries use /api/graphql. The wrong endpoint returns empty data without an error, so check the response body, not just the 200 status.

Before opening a pull request

  • npm test passes.

  • You tried the new tool against real Instagram. Put the evidence in the PR description, for example how many items came back.

  • Any change you made to the account while testing (likes, follows, comments) has been undone.

  • The commit contains no cookies, tokens, or personal account data.

Project layout

src/
  browser.ts      Chrome, GraphQL query capture, and request sending
  ig/             Instagram client, queue, and data normalization
  tools/          All MCP tools, grouped by feature
  leads/          Lead storage and scoring
  mcp.ts          MCP server over stdio and HTTP
scripts/          Test and debug helpers
test/             Unit tests
examples/         Example lead configs
docker/           Container entrypoint (Chromium + noVNC)

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Instagram Business accounts by automating content publishing, scheduling posts, and analyzing performance metrics. Supports posts, stories, reels, and carousels with detailed audience insights and hashtag discovery.
      1
      -
    • A
      license
      A
      quality
      F
      maintenance
      Enables AI assistants to interact with Instagram by scraping profiles, posts, reels, DMs, and business insights through a robust, DOM-agnostic browser orchestration engine that bypasses Instagram's anti-automation measures.
      28
      1
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to manage a personal Instagram account through a logged-in browser session, supporting actions like reading profiles and DMs, publishing posts, reels, and stories, scheduling content, and accessing insights and audience reports.
      60
      247 npm
      14
      MIT