Skip to main content
Glama
unofficial-instagram-mcp

unofficial-instagram-mcp

by fanyzp

An unofficial Model Context Protocol (MCP) server for Instagram Web. It gives an AI agent a set of focused tools for messages, profiles, posts, comments, stories, and notifications.

The server connects to a Chrome window that is already signed in to Instagram. It does not use the Meta API, and it does not ask for or store an Instagram password.

Quick start (no clone needed)

One command installs everything into your agent: it registers the MCP server and installs the Agent Skill. Pick your harness in the menu.

npx github:fanyzp/unofficial-instagram-mcp install

Or register the server in your MCP client config and let it run through npx directly:

{
  "mcpServers": {
    "instagram": {
      "command": "npx",
      "args": ["-y", "github:fanyzp/unofficial-instagram-mcp"],
      "env": { "CDP_URL": "http://127.0.0.1:9222", "IG_DRY_RUN": "true" }
    }
  }
}

Then start Chrome as described below and call ig_status. Prefer working from source instead? Use the clone based install after this section.

Test first. After connecting, run the built-in self-test to make sure every feature works end to end on your setup: call the ig_selftest tool or run npm run selftest. The default level only reads. The full level (npm run selftest -- full) exercises every write function on content it creates itself, then deletes all of it at the end. Use a second account for testing, not your main account.

Related MCP server: Instagram MCP Server

What it does

The server provides the capability layer. The user and the agent decide how to use it.

Use it to:

  • Read and reply to Instagram direct messages.

  • Check profiles, followers, following lists, posts, comments, stories, and notifications.

  • Search users and hashtags, and browse the home feed, Explore page, and hashtag pages.

  • Like posts and comments, reply to a specific comment, save posts, follow or unfollow users, and create posts.

  • Run the same tools from an MCP client, the command line, or the interactive TUI.

The MCP tools use standard annotations. Read tools use readOnlyHint, and write tools use destructiveHint. The server also returns instructions that tell the agent to call ig_status first and to respect the dryRun, sent, and alreadyLiked fields in tool results.

In use

An agent session in OpenCode, working through the MCP tools:

How it works

MCP client, CLI, or TUI
          |
          v
unofficial-instagram-mcp
          |
          v
Playwright Core over CDP
          |
          v
Chrome window signed in to Instagram Web

All actions use the visible Instagram web interface. The project does not call private Instagram APIs. Selectors are kept in config/selectors.json, so most interface changes can be fixed in one place.

Requirements

  • Node.js 20 or newer

  • Google Chrome or Chromium

  • An Instagram account signed in in that browser

  • An MCP client, if you plan to use the MCP server

Install from source

git clone https://github.com/fanyzp/unofficial-instagram-mcp.git
cd unofficial-instagram-mcp
npm install
cp .env.example .env

On Windows PowerShell, copy the environment file with:

Copy-Item .env.example .env

Keep IG_DRY_RUN=true for the first run. In dry run mode, write tools prepare and report the action without completing it.

Start Chrome

Start Chrome with remote debugging enabled, then sign in to Instagram manually in that window.

Linux example:

google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.local/share/unofficial-instagram-mcp/chrome"

The default CDP address is http://127.0.0.1:9222. Keep the debugging port available only on your own machine. Any local process that can reach this port can control the signed-in browser session.

Give this to your AI agent

Paste this into your coding agent if you want it to set everything up for you:

Set up unofficial-instagram-mcp for me and learn how it works before using it.

1. Read the Agent Skill first: https://github.com/fanyzp/unofficial-instagram-mcp/blob/main/skills/unofficial-instagram-mcp/SKILL.md
   It explains how the server works, the tool map, the workflows, and the safety rules. Follow it from now on.
2. Run the installer for your own harness: npx github:fanyzp/unofficial-instagram-mcp install --harness <your-harness-id> --scope user --yes
   Harness ids: claude-code, opencode, cursor, codex, gemini-cli, pi, oh-my-pi, openclaw, zcode, goose, amp, vscode, claude-desktop, windsurf, zed, generic.
   T3 Code has no MCP config of its own: it runs other providers and reads their configs, so use claude-code or codex for it.
   If your harness is not listed, register the server manually with command "npx" and args ["-y", "github:fanyzp/unofficial-instagram-mcp"], env CDP_URL=http://127.0.0.1:9222 and IG_DRY_RUN=true, and copy the skills/unofficial-instagram-mcp folder into your agent skills directory, keeping the folder name unchanged.
3. Start Chrome with remote debugging on port 9222 if it is not running yet. I will sign in to Instagram manually. Do not ask for or store my password.
4. Call ig_status first and confirm the signed-in username with me.
5. Before any write action, show me the exact target and content. Do not disable dry run unless I approve it.

MCP configuration

Most MCP clients use a configuration like this. Replace the path with the absolute path to your clone.

{
  "mcpServers": {
    "instagram": {
      "command": "node",
      "args": [
        "/absolute/path/to/unofficial-instagram-mcp/src/server.js"
      ],
      "env": {
        "CDP_URL": "http://127.0.0.1:9222",
        "IG_DRY_RUN": "true"
      }
    }
  }
}

OpenCode

Add the server under the mcp key in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "instagram": {
      "type": "local",
      "command": [
        "node",
        "/absolute/path/to/unofficial-instagram-mcp/src/server.js"
      ],
      "enabled": true,
      "environment": {
        "CDP_URL": "http://127.0.0.1:9222",
        "IG_DRY_RUN": "true"
      }
    }
  }
}

After registration, restart the MCP client and ask the agent to call ig_status.

Updating

Run the update command. It re-runs the installer with --force, which refreshes the Agent Skill files and rewrites the MCP registration with the latest version:

npx github:fanyzp/unofficial-instagram-mcp update

Installed from a clone instead? Run git pull, then node bin/install.mjs --force. If npx ever serves a stale cached copy, delete the ~/.npm/_npx folder and run the command again. Or simply tell your agent: "update unofficial-instagram-mcp".

Agent skill

This repository ships an Agent Skills skill at skills/unofficial-instagram-mcp/SKILL.md. The MCP server gives the agent the tools; the skill teaches it how the server works, when to use each tool, the standard workflows, and the safety rules.

Installing both is the intended setup. The skill loads by progressive disclosure, so the agent carries only its name and description in context and reads the full instructions when an Instagram task comes up, instead of needing a long briefing in every session.

Four ways to install:

1. One command through npx (MCP server + skill together, no clone). This is the bundled installer running straight from GitHub:

npx github:fanyzp/unofficial-instagram-mcp install

It asks for the scope and the harness, then registers the MCP server and installs the skill in one run. Non-interactive form: add --harness <id> --scope user --yes.

2. The standard skills CLI. The open Agent Skills installer discovers the skill in this repository and lets you choose which agents (harnesses) to install it to:

npx skills add fanyzp/unofficial-instagram-mcp

Add -g for a user-wide install, or pin targets directly, for example npx skills add fanyzp/unofficial-instagram-mcp -g -a claude-code -a opencode. This installs the skill only; register the MCP server with the installer below or by hand.

3. The bundled installer from a clone. Same installer as route 1, run from a local clone of this repository:

node bin/install.mjs

It asks for the scope (user or this project) and the harness (16 targets: Claude Code, OpenCode, Cursor, Codex, Gemini CLI, Pi, Oh My Pi, OpenClaw, ZCode, Goose, Amp, VS Code, Claude Desktop, Windsurf, Zed, or a generic .agents/skills target; run it with --list for the ids), registers the instagram MCP server in that harness's own config format, and copies the skill into its skills directory where the harness supports skill folders. Existing config files are merged, not replaced. Non-interactive form:

node bin/install.mjs --harness claude-code,opencode --scope user --yes
node bin/install.mjs --all --scope project --dry-run

4. By hand. Copy the folder into your agent's skills directory (for example ~/.claude/skills/ for Claude Code, or the skills directory your client documents), keeping the folder name unofficial-instagram-mcp unchanged:

cp -r skills/unofficial-instagram-mcp ~/.claude/skills/

CLI usage

List the available tools:

node src/cli.js tools

Run a few read operations:

node src/cli.js ig_status
node src/cli.js dm_check --limit 5
node src/cli.js dm_read_thread --threadId <thread-id>
node src/cli.js profile_get --username fanyzts
node src/cli.js search --query "balikpapan"
node src/cli.js post_comments --url <post-url> --limit 20

Write operations use the same form:

node src/cli.js dm_send --threadId <thread-id> --text "Thanks, I will check and reply soon."
node src/cli.js post_like --url <post-url>
node src/cli.js post_create --files ./photo.jpg --caption "Posted with an AI agent."

With IG_DRY_RUN=true, these commands report what would happen instead of completing the action.

TUI usage

The TUI is the direct way to test the tools by hand. The main menu lists the tool categories (System, DM, Profile & Search, Posts, Discovery, Social, Stories); each category opens a sub-menu of its tools. It runs the tools against your live session right away and prints the raw result of each call:

npm run tui

Tools

Account and messages

Tool

Description

ig_status

Check the browser connection and the signed-in account.

ig_selftest

Run the built-in self-test. The safe level only reads; the full level tests every write function and deletes its own test content.

dm_list_threads

List recent DM threads. Opening a thread can mark it as read.

dm_check

Find threads where the latest message came from the other person.

dm_read_thread

Read the latest messages in one thread.

dm_send

Send a message in an existing thread.

dm_send_to_user

Send a message to a user by username.

notifications_list

Read recent likes, comments, follows, and mentions.

Profiles and social graph

Tool

Description

profile_get

Read a profile, including counts and bio text.

search

Search from a keyword and return matching users, hashtags, posts, and reels shown by Instagram.

followers_list

List followers for a profile.

following_list

List accounts followed by a profile.

user_follow

Follow a user.

user_unfollow

Unfollow a user.

Content

Tool

Description

user_posts

List recent posts and reels from a profile.

post_get

Read the author, time, media type, caption, and visible page text for a post.

post_comments

Read comments on a post.

feed_home

Read recent posts from the home feed.

explore_posts

List posts from the Explore page.

hashtag_posts

List posts from a hashtag page.

media_urls

Return the image and video URLs used by a post.

stories_tray

List accounts with an active story in the home tray.

story_view

Open a user story. Viewing it marks the story as seen.

Actions

Tool

Description

post_create

Create a post from local image files and a caption.

post_like

Like a post or reel. Safe to call again if it is already liked.

post_comment

Add a comment to a post or reel.

post_reply_to_comment

Reply to one comment that matches the supplied text.

comment_like

Like one comment that matches the supplied text.

post_save

Save a post. Safe to call again if it is already saved.

post_delete

Delete one of your own posts by URL. Refuses posts owned by someone else.

story_reply

Reply to a user story. The reply is delivered as a direct message.

story_create

Create a story from an image file, or a text story when the web text editor is available. Not offered by Instagram Web for every account; see docs/VERIFICATION.md.

story_create_poll

Create a story with a poll sticker: a question and two options, on an image. Subject to the same Instagram Web limitation as story_create.

story_delete

Delete your own currently active story.

Common workflows

Check and answer messages:

ig_status -> dm_check -> dm_read_thread -> dm_send

Join a discussion under a post:

post_comments -> post_reply_to_comment

Research a topic:

search or hashtag_posts -> post_get -> post_comments -> media_urls

Check engagement before replying:

notifications_list -> post_comments or dm_check

Self-test

The project ships with a self-test so you can verify the whole feature set on your own setup before real use. It is a recommendation, not a requirement.

Safe level, read only, works on any account:

npm run selftest

Or call the ig_selftest tool from your MCP client with { "level": "safe" }.

Full level: creates its own test post and story, runs every write function against them (like, comment, reply, comment like, save, follow state restore, story view), then deletes everything it created. It only runs when all three gates are set in .env, and it refuses to run when the signed-in account does not match IG_SELFTEST_ACCOUNT:

IG_SELFTEST_FULL=true
IG_DRY_RUN=false
IG_SELFTEST_ACCOUNT=<username of your second account>
npm run selftest -- full

Use a second account for the full level, not your main account. The test cleans up after itself, but a second account keeps your main account's history and risk profile untouched.

Set IG_SELFTEST_ON_CONNECT=true if you want the safe level to run once automatically when the MCP server first connects. The result is written to the server log (stderr).

Configuration

The server reads values from the environment and from .env in the project root.

Variable

Default

Description

CDP_URL

http://127.0.0.1:9222

Chrome DevTools Protocol address.

USER_DATA_DIR

Empty

Optional persistent browser profile. When set, the server opens that profile instead of connecting over CDP. Sign in manually once.

IG_DRY_RUN

true

When true, write tools simulate the final action. Set to false only when you are ready to perform real actions.

MIN_DELAY_MS

2500

Minimum delay between browser actions, in milliseconds.

MAX_DELAY_MS

7000

Maximum delay between browser actions, in milliseconds.

IG_SELFTEST_ON_CONNECT

false

When true, the safe self-test runs once when the MCP server first connects.

IG_SELFTEST_FULL

false

Gate for the full self-test level. Must be true together with the two settings below.

IG_SELFTEST_ACCOUNT

Empty

Username the full self-test is allowed to run on. It refuses to run on any other account.

IG_SELFTEST_TARGET

instagram

Account used for the follow and restore step of the full self-test.

IG_SELFTEST_DM_TARGET

Empty

Optional. Your own second account, used once for the dm_send_to_user step of the full self-test.

Safety and limits

  • This is an unofficial project. It is not affiliated with Meta or Instagram.

  • Use it only with your own account or an account you are authorized to operate.

  • Keep dry run enabled while testing. Check the target, text, and result before approving a real action.

  • Opening a DM thread can mark it as read. Viewing a story marks it as seen.

  • Instagram can change its web interface without notice. When that happens, selectors or page flows may need an update.

  • Instagram may limit or restrict automated activity. Use reasonable delays and volume, and stop if Instagram shows a warning or checkpoint.

  • A real signed-in browser makes the actions look like normal web use, but it does not guarantee that an account will never be limited.

Verification status

Every tool was live tested on a second account on 16 November 2026: 31 of 34 tools pass. The 3 remaining tools (story_create, story_create_poll, story_delete) are blocked by an Instagram Web platform limitation, not by this code.

Full per-tool results, the test environment, and the run notes live in docs/VERIFICATION.md.

Development

Project layout:

src/server.js       MCP server over stdio
src/tools.js        Tool definitions, categories, and MCP annotations
src/instagram.js    Instagram web actions
src/browser.js      CDP and persistent profile handling
src/cli.js          Command line interface
src/tui.js          Interactive terminal interface (category sub-menus)
src/selftest.js     Built-in self-test, safe and full levels
src/run-selftest.js CLI runner for the self-test
bin/install.mjs     Installer: registers the MCP server and installs the skill per harness
config/selectors.json
skills/unofficial-instagram-mcp/SKILL.md   Agent skill that teaches agents this server
test/mcp.test.mjs   MCP protocol tests that do not need a browser
test/fixtures/      Image used by the full self-test

Run the checks:

npm run check
npm test

The test suite covers the MCP handshake, tool discovery, annotations, server instructions, ping, unknown methods, a tool call made without a browser connection, and the self-test gate that refuses the full level without its safety settings.

License

MIT

Available Tools

34 tools
comment_likeB
Destructive

Like satu komentar spesifik (cari yang memuat teks match). AKSI TULIS kecuali IG_DRY_RUN=true.

Inputs: url (required), match (required).

dm_checkB
Read-only

Cek thread mana yang pesan terakhirnya dari lawan bicara (perlu dibalas). Baca saja, tidak membalas apa pun.

Inputs: limit.

dm_list_threadsC
Read-only

Daftar thread DM teratas (klik-scan, karena daftar IG menyusut jadi avatar). EFEK SAMPING: membuka thread dapat menandainya terbaca.

Inputs: limit.

dm_read_threadB
Read-only

Baca isi 1 thread DM: username, nama, dan pesan-pesan terakhir dengan arahnya (fromMe true = pesan akun sendiri).

Inputs: threadId (required), limit.

dm_sendA
Destructive

Kirim / balas pesan di thread DM yang sudah ada (berdasarkan threadId). AKSI TULIS: benar-benar terkirim kecuali IG_DRY_RUN=true.

Inputs: text (required), threadId (required).

dm_send_to_userB
Destructive

Kirim DM ke username tertentu (buka profil, klik Message, lalu kirim). AKSI TULIS seperti dm_send.

Inputs: text (required), username (required).

explore_postsC
Read-only

Daftar post dari halaman Explore saat ini.

Inputs: limit.

feed_homeB
Read-only

Intip timeline beranda akun yang login (postingan terbaru + penulisnya).

Inputs: limit.

followers_listB
Read-only

Daftar username followers seorang user (dari dialog followers). Batas hasil mengikuti yang dimuat IG.

Inputs: username (required), limit.

following_listB
Read-only

Daftar username yang di-follow seorang user (dari dialog following).

Inputs: username (required), limit.

hashtag_postsC
Read-only

Daftar post di halaman sebuah hashtag. Berguna untuk riset topik/niche.

Inputs: tag (required), limit.

ig_selftestA
Destructive

Jalankan self-test resmi. Level "safe" (default): hanya tool baca, aman di akun mana pun. Level "full": menguji SEMUA tool tulis pada konten buatan sendiri lalu MENGHAPUS semuanya di akhir; gerbang keras IG_SELFTEST_FULL=true + IG_DRY_RUN=false + IG_SELFTEST_ACCOUNT harus sama dengan akun login. PERINGATAN: level full hanya di akun kedua, jangan akun utama.

Inputs: level.

ig_statusA
Read-only

Cek koneksi browser & akun Instagram yang sedang login. Panggil ini pertama kali.

Inputs: no named parameters.

media_urlsA
Read-only

Ambil URL file gambar/video dari sebuah post (untuk diunduh/diolah agent).

Inputs: url (required).

notifications_listB
Read-only

Baca panel notifikasi: like/komen/follow/mention terbaru ke akun yang login. Kunci untuk engagement: dari sini agent tahu siapa yang harus dibalas.

Inputs: limit.

post_commentB
Destructive

Komentar baru di post/reel dari URL-nya. AKSI TULIS kecuali IG_DRY_RUN=true.

Inputs: url (required), text (required).

post_commentsA
Read-only

Baca komentar-komentar sebuah post. Pasangan baca dari post_reply_to_comment: baca dulu, putuskan, baru balas.

Inputs: url (required), limit.

post_createB
Destructive

Buat post baru dari file gambar lokal + caption. Dengan IG_DRY_RUN=true berhenti tepat sebelum tombol Share.

Inputs: files (required), caption.

post_deleteA
Destructive

Hapus post MILIK SENDIRI dari URL-nya. Menolak bila penulisnya bukan akun yang login. AKSI TULIS kecuali IG_DRY_RUN=true.

Inputs: url (required).

post_getB
Read-only

Detail sebuah post/reel: penulis, waktu, jenis media, dan teks halaman (caption, jumlah like/komen bila tampil).

Inputs: url (required).

post_likeA
Destructive

Like sebuah post/reel dari URL-nya. Idempotent: kalau sudah di-like, dilaporkan alreadyLiked. AKSI TULIS kecuali IG_DRY_RUN=true.

Inputs: url (required).

post_reply_to_commentA
Destructive

Balas SATU komentar spesifik di sebuah post: cari komentar yang memuat teks match, klik Reply, lalu kirim balasan. AKSI TULIS kecuali IG_DRY_RUN=true.

Inputs: url (required), text (required), match (required).

post_saveB
Destructive

Simpan (bookmark) sebuah post. Idempotent. AKSI TULIS kecuali IG_DRY_RUN=true.

Inputs: url (required).

profile_getA
Read-only

Ambil info profil Instagram (bio, jumlah post/followers/following). Tanpa username = profil akun yang login.

Inputs: username.

stories_trayB
Read-only

Daftar akun dengan story aktif di tray beranda saat ini (untuk memilih story mana yang dilihat).

Inputs: limit.

story_createA
Destructive

Buat story baru: dari file gambar, atau story teks (text) bila editor teks IG web tersedia untuk akun ini. BATASAN PLATFORM: Instagram Web tidak selalu menyediakan pintu pembuatan story (terverifikasi 16 Nov 2026: akun uji tidak punya entry point story sama sekali di web); tool melaporkan itu dengan jelas bila tidak tersedia. AKSI TULIS kecuali IG_DRY_RUN=true.

Inputs: file, text.

story_create_pollA
Destructive

Buat story dengan stiker POLLING: question + 2 options (bawaan IG) di atas file gambar. Gagal dengan alasan jelas bila pembuatan story / stiker tidak tersedia di IG web akun ini; story tidak dibagikan bila polling gagal terpasang. AKSI TULIS kecuali IG_DRY_RUN=true.

Inputs: question (required), file, options.

story_deleteA
Destructive

Hapus story aktif MILIK SENDIRI yang sedang tayang. AKSI TULIS kecuali IG_DRY_RUN=true.

Inputs: no named parameters.

story_replyB
Destructive

Balas story seorang user dengan teks (masuk sebagai DM). AKSI TULIS kecuali IG_DRY_RUN=true.

Inputs: text (required), username (required).

story_viewA
Destructive

Buka story seorang user dan laporkan isinya secara ringkas. EFEK: story tertanda sudah dilihat.

Inputs: username (required).

user_followA
Destructive

Follow seorang user. Idempotent: state Following/Requested dilaporkan apa adanya. AKSI TULIS kecuali IG_DRY_RUN=true.

Inputs: username (required).

user_postsC
Read-only

Daftar post/reel terbaru dari profil seorang user (URL saja). Berguna untuk riset konten & monitoring kompetitor.

Inputs: username (required), limit.

user_unfollowA
Destructive

Unfollow seorang user (dengan dialog konfirmasi IG). AKSI TULIS kecuali IG_DRY_RUN=true.

Inputs: username (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 34 tools

    Disambiguation4/5

    The domain prefixes (dm_, post_, story_, user_) plus descriptors make most boundaries clear, and paired read/write tools are explicitly linked in their descriptions (post_comments ↔ post_reply_to_comment, stories_tray ↔ story_view). A few pairs still need care: story_create vs story_create_poll, dm_list_threads vs dm_check vs dm_read_thread, and post_get vs media_urls vs post_comments all touch the same resource and could be mispicked by a hurried agent.

    Naming Consistency3/5

    Theming is recognizable but conventions are mixed: dm_list_threads/dm_read_thread/dm_send are verb-first, whereas post_like, post_get, user_follow, and profile_get are noun-first, and un-prefixed names like `search` sit alongside prefixed ones. The story family is also split between the singular `story_*` (view, reply, create, delete) and plural `stories_tray`, which breaks the otherwise tidy prefix scheme.

    Tool Count3/5

    34 tools is heavy for a single-account browser automation surface, and a handful (media_urls, explore_posts, ig_selftest, story_create_poll) feel like variants rather than independent capabilities. That said, the breadth mirrors the real Instagram web surface (DMs, posts, comments, stories, social graph), so most tools map to a distinct UI action rather than bloat.

    Completeness4/5

    Read/write coverage is genuinely broad: DMs, posts, comments, stories, follows, search, feed/explore/hashtag browsing, notifications, and a documented self-test harness, with sane idempotency and dry-run semantics. The gaps are mostly inverse operations (unlike, unsave, delete comment, delete DM, block/report) and no post/profile editing, which agents can work around but leave the lifecycle slightly asymmetric.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables users to send Instagram Direct Messages, manage chats and messages, download media from conversations, and retrieve user, story, follower, and post information through natural-language tool calls.
      -