unofficial-instagram-mcp
Provides tools for interacting with Instagram Web through a signed-in Chrome session, enabling AI agents to read and reply to direct messages; inspect profiles, followers, posts, comments, stories, and notifications; search users and hashtags; browse feeds and Explore; and perform actions such as liking, saving, following, and creating posts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@unofficial-instagram-mcp check my unread Instagram DMs and reply to the latest one"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 installOr 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_selftesttool or runnpm 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 WebAll 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 .envOn Windows PowerShell, copy the environment file with:
Copy-Item .env.example .envKeep 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 updateInstalled 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 installIt 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-mcpAdd -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.mjsIt 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-run4. 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 toolsRun 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 20Write 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 tuiTools
Account and messages
Tool | Description |
| Check the browser connection and the signed-in account. |
| Run the built-in self-test. The safe level only reads; the full level tests every write function and deletes its own test content. |
| List recent DM threads. Opening a thread can mark it as read. |
| Find threads where the latest message came from the other person. |
| Read the latest messages in one thread. |
| Send a message in an existing thread. |
| Send a message to a user by username. |
| Read recent likes, comments, follows, and mentions. |
Profiles and social graph
Tool | Description |
| Read a profile, including counts and bio text. |
| Search from a keyword and return matching users, hashtags, posts, and reels shown by Instagram. |
| List followers for a profile. |
| List accounts followed by a profile. |
| Follow a user. |
| Unfollow a user. |
Content
Tool | Description |
| List recent posts and reels from a profile. |
| Read the author, time, media type, caption, and visible page text for a post. |
| Read comments on a post. |
| Read recent posts from the home feed. |
| List posts from the Explore page. |
| List posts from a hashtag page. |
| Return the image and video URLs used by a post. |
| List accounts with an active story in the home tray. |
| Open a user story. Viewing it marks the story as seen. |
Actions
Tool | Description |
| Create a post from local image files and a caption. |
| Like a post or reel. Safe to call again if it is already liked. |
| Add a comment to a post or reel. |
| Reply to one comment that matches the supplied text. |
| Like one comment that matches the supplied text. |
| Save a post. Safe to call again if it is already saved. |
| Delete one of your own posts by URL. Refuses posts owned by someone else. |
| Reply to a user story. The reply is delivered as a direct message. |
| 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. |
| Create a story with a poll sticker: a question and two options, on an image. Subject to the same Instagram Web limitation as |
| Delete your own currently active story. |
Common workflows
Check and answer messages:
ig_status -> dm_check -> dm_read_thread -> dm_sendJoin a discussion under a post:
post_comments -> post_reply_to_commentResearch a topic:
search or hashtag_posts -> post_get -> post_comments -> media_urlsCheck engagement before replying:
notifications_list -> post_comments or dm_checkSelf-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 selftestOr 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 -- fullUse 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 |
|
| Chrome DevTools Protocol address. |
| Empty | Optional persistent browser profile. When set, the server opens that profile instead of connecting over CDP. Sign in manually once. |
|
| When |
|
| Minimum delay between browser actions, in milliseconds. |
|
| Maximum delay between browser actions, in milliseconds. |
|
| When |
|
| Gate for the full self-test level. Must be |
| Empty | Username the full self-test is allowed to run on. It refuses to run on any other account. |
|
| Account used for the follow and restore step of the full self-test. |
| Empty | Optional. Your own second account, used once for the |
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-testRun the checks:
npm run check
npm testThe 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
Available Tools
34 toolscomment_likeBDestructive
Like satu komentar spesifik (cari yang memuat teks match). AKSI TULIS kecuali IG_DRY_RUN=true.
Inputs: url (required), match (required).
dm_checkBRead-only
Cek thread mana yang pesan terakhirnya dari lawan bicara (perlu dibalas). Baca saja, tidak membalas apa pun.
Inputs: limit.
dm_list_threadsCRead-only
Daftar thread DM teratas (klik-scan, karena daftar IG menyusut jadi avatar). EFEK SAMPING: membuka thread dapat menandainya terbaca.
Inputs: limit.
dm_read_threadBRead-only
Baca isi 1 thread DM: username, nama, dan pesan-pesan terakhir dengan arahnya (fromMe true = pesan akun sendiri).
Inputs: threadId (required), limit.
dm_sendADestructive
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_userBDestructive
Kirim DM ke username tertentu (buka profil, klik Message, lalu kirim). AKSI TULIS seperti dm_send.
Inputs: text (required), username (required).
explore_postsCRead-only
Daftar post dari halaman Explore saat ini.
Inputs: limit.
feed_homeBRead-only
Intip timeline beranda akun yang login (postingan terbaru + penulisnya).
Inputs: limit.
followers_listBRead-only
Daftar username followers seorang user (dari dialog followers). Batas hasil mengikuti yang dimuat IG.
Inputs: username (required), limit.
following_listBRead-only
Daftar username yang di-follow seorang user (dari dialog following).
Inputs: username (required), limit.
hashtag_postsCRead-only
Daftar post di halaman sebuah hashtag. Berguna untuk riset topik/niche.
Inputs: tag (required), limit.
ig_selftestADestructive
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_statusARead-only
Cek koneksi browser & akun Instagram yang sedang login. Panggil ini pertama kali.
Inputs: no named parameters.
media_urlsARead-only
Ambil URL file gambar/video dari sebuah post (untuk diunduh/diolah agent).
Inputs: url (required).
notifications_listBRead-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_commentBDestructive
Komentar baru di post/reel dari URL-nya. AKSI TULIS kecuali IG_DRY_RUN=true.
Inputs: url (required), text (required).
post_commentsARead-only
Baca komentar-komentar sebuah post. Pasangan baca dari post_reply_to_comment: baca dulu, putuskan, baru balas.
Inputs: url (required), limit.
post_createBDestructive
Buat post baru dari file gambar lokal + caption. Dengan IG_DRY_RUN=true berhenti tepat sebelum tombol Share.
Inputs: files (required), caption.
post_deleteADestructive
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_getBRead-only
Detail sebuah post/reel: penulis, waktu, jenis media, dan teks halaman (caption, jumlah like/komen bila tampil).
Inputs: url (required).
post_likeADestructive
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_commentADestructive
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_saveBDestructive
Simpan (bookmark) sebuah post. Idempotent. AKSI TULIS kecuali IG_DRY_RUN=true.
Inputs: url (required).
profile_getARead-only
Ambil info profil Instagram (bio, jumlah post/followers/following). Tanpa username = profil akun yang login.
Inputs: username.
searchCRead-only
Cari user & hashtag di Instagram dari kata kunci.
Inputs: query (required), limit.
stories_trayBRead-only
Daftar akun dengan story aktif di tray beranda saat ini (untuk memilih story mana yang dilihat).
Inputs: limit.
story_createADestructive
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_pollADestructive
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_deleteADestructive
Hapus story aktif MILIK SENDIRI yang sedang tayang. AKSI TULIS kecuali IG_DRY_RUN=true.
Inputs: no named parameters.
story_replyBDestructive
Balas story seorang user dengan teks (masuk sebagai DM). AKSI TULIS kecuali IG_DRY_RUN=true.
Inputs: text (required), username (required).
story_viewADestructive
Buka story seorang user dan laporkan isinya secara ringkas. EFEK: story tertanda sudah dilihat.
Inputs: username (required).
user_followADestructive
Follow seorang user. Idempotent: state Following/Requested dilaporkan apa adanya. AKSI TULIS kecuali IG_DRY_RUN=true.
Inputs: username (required).
user_postsCRead-only
Daftar post/reel terbaru dari profil seorang user (URL saja). Berguna untuk riset konten & monitoring kompetitor.
Inputs: username (required), limit.
user_unfollowADestructive
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
Scored across 34 tools
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.
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.
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.
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
Related MCP Connectors
Instagram for AI agents: publish, read comments and DMs, insights, and engage from your account.
Instagram search and posts for AI agents, with images and videos AI-parsed to text.
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Instagram MCP for DM and comment automation, AI Agent and content publishing via Meta's official API
Related MCP Servers
- FlicenseBqualityDmaintenanceEnables AI agents to control Instagram accounts programmatically, supporting profile management, media interaction, direct messaging, and follower management.132-
- AlicenseAqualityFmaintenanceEnables 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.281Apache 2.0

@inssist/mcpofficial
AlicenseAqualityBmaintenanceEnables 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.60247 npm14MIT- FlicenseNot gradedqualityAmaintenanceEnables 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.-