instagram-mcp
Provides integration with Instagram via its private mobile API, enabling reading of profiles, posts, stories, followers, comments, and DMs, plus optional write actions like posting, liking, commenting, following, and sending direct messages when explicitly enabled.
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., "@instagram-mcp check my recent Instagram DMs and tell me if anything needs a reply"
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.
instagram-mcp
An MCP server that exposes instagrapi — Instagram's private mobile API — as 49 tools an agent can call.
Reading is enabled out of the box. Anything that changes the account (posting, liking, following, commenting, DMing, deleting) is refused until you explicitly turn writes on.
Setup
cp .env.example .envThen fill in .env with either a username and password, or a sessionid
cookie copied from a browser where you are already signed in (DevTools →
Application → Cookies → instagram.com). The sessionid route is less likely to
trigger a login challenge.
If the account uses two-factor auth, paste the authenticator "setup key" into
INSTAGRAM_TOTP_SEED and codes are generated for you. Otherwise, when Instagram
asks for a code, call instagram_login with verification_code.
Verify the install without touching Instagram:
.venv/Scripts/python smoke_test.pyRelated MCP server: Instagram MCP Server
Registering the server
Already registered for this project in ../.mcp.json. To use it elsewhere:
claude mcp add instagram -- "C:\Users\osami\OneDrive\Documents\GitHub\ayham project 2\instagram-mcp\.venv\Scripts\instagram-mcp.exe"The executable works from any directory — it always reads .env and writes
session.json next to this README.
Enabling write actions
INSTAGRAM_ALLOW_WRITES=trueRestart the server afterwards. While this is false, write tools fail with an
explanation rather than doing anything, so the read-only tools stay usable.
Tools
Group | Tools |
Writing DMs |
|
Persona search |
|
Session |
|
Users |
|
Posts |
|
Discovery |
|
Direct messages |
|
Engagement |
|
Publishing |
|
* requires INSTAGRAM_ALLOW_WRITES=true.
Users are addressed by username or user_id. Posts are addressed by a media
argument that accepts a post URL, a shortcode, or a numeric media id.
Writing DMs in your own voice
This is what the server is mainly for. The problem with letting a model write your messages is that it writes correctly — punctuated, capitalised, polite — and everyone who knows you can tell instantly.
So instagram_build_style_profile measures how you actually write, from your
own sent DMs: message length, capitalisation, terminal punctuation, emoji rate,
which emoji, how you spell laughter, shorthand, language mixing, and whether you
send bursts of short messages instead of one composed one. It records this
globally and per contact, because nobody writes to their mother the way they
write to their closest friend.
Run it once:
.venv/Scripts/python -c "import asyncio,json;from instagram_mcp.server import server;print(asyncio.run(server.call_tool('instagram_build_style_profile',{})).content[0].text[:400])"After that, instagram_prepare_dm(person="sarah") returns — in one call — the
recent conversation, the measured rules of your voice, and samples of how you
write to that specific person. That single call is the whole interface for
drafting; there is no need to stitch together the raw thread tools.
The profile is cached in style_profile.json and never sent to Instagram.
Refresh it occasionally as your writing drifts.
The skill
~/.claude/skills/instagram-dm/SKILL.md drives the whole workflow in normal
conversation — "reply to ahmed", "what should I say back to her", "check my
ig messages". It handles finding the person, loading your voice, drafting, and
holding the draft for your approval before anything sends.
Nothing sends without you seeing the exact words first.
Finding people who match a persona
The other thing the server is for. You describe someone — female, Amsterdam, fitness, mid-twenties, blonde — and get back ranked profiles with a confidence figure per attribute.
The hard part is that Instagram has no index for any of that. It indexes four things: handle and name text, hashtags, place geotags, and the follow graph. A persona is none of them. So every attribute is either compiled into a probe against one of those four, or inferred afterwards from what came back — which makes this a funnel that trades recall for precision, not a query.
recall hundreds of candidates, mostly wrong, from many cheap probes
gate free: drops private accounts and shops
expand chaining off the best survivors — the highest-precision channel
enrich ~3 API calls each. The expensive stage, so it runs on a ranked subset
signals free: name, pronouns, geotag clusters, captions, category, birth years
judge vision, on the shortlist only, from one contact sheet per candidate
results ranked, with every piece of evidence attachedWhat makes it work is instagram_similar_accounts, which reads Instagram's own
"Suggested for you" graph, built from co-follow behaviour it already models. Once
you have one good match, chaining outward from it beats any keyword search by a
wide margin — which is why the text and hashtag probes exist mainly to find that
first foothold.
Location is the other thing worth knowing about. Instagram's city field is
almost always null and occasionally wrong — one live probe returned a place
called "Hollanda" carrying coordinates in Alexandria, Egypt — and place names
fragment badly, with one city arriving as "Amsterdam, Netherlands", "Amsterdam
Canal District", "Red Light District, Amsterdam" and "Amsterdam Canal River".
Coordinates are always present, so geotags are clustered by position rather than
by name: the variants merge, and the mislabelled entry excludes itself.
One thing the design originally leaned on turned out not to exist. Instagram generates alt text for photos ("may be an image of 1 person, blonde hair, standing"), which would have been free coarse vision on every post — but it is only exposed to the web client, and came back empty on all thirty-two posts of a live probe. Appearance therefore costs a real look at real images, and the ceilings reflect that rather than pretending otherwise.
A search is a job on disk, not a function call: a real one is several hundred API calls over ten or twenty minutes against an account Instagram will rate limit, so it runs stage by stage, survives a crash, and lets you fix a bad probe plan after twenty calls instead of three hundred.
instagram_search_start(persona={"gender": {"value": "female", "required": true},
"city": "Amsterdam", "niche": ["fitness"],
"age_band": [24, 32], "hair": "blonde"})
instagram_search_recall(search_id, probes={"hashtags": [{"tag": "fitgirlnl"}],
"places": [{"query": "Amsterdam gym"}],
"accounts": [{"query": "amsterdam fitness"}]})
instagram_search_gate(search_id) # free
instagram_search_expand(search_id) # chain off the best
instagram_search_enrich(search_id, limit=40)
instagram_search_signals(search_id) # free, and resolves most personas outright
instagram_search_results(search_id, limit=20)Judging the pictures
Appearance is the one thing no free signal reaches, so it has to be looked at.
instagram_search_shortlist(download_images=true) fetches each candidate's
profile picture and recent thumbnails and composes them into a single numbered
contact sheet, rather than handing over a dozen loose files.
That is not just tidier. It costs a twelfth of the attention, the numbers let a
judgement cite the tile it came from, and it makes the hardest question
answerable: which of these faces is the account holder? Feeds are full of
friends, partners and clients, and a judgement made on the wrong face arrives
sounding exactly as confident as a right one. Seeing every picture side by side
turns that into something you can just look at - find the recurring face, check
it against the tile marked avatar, which is the only picture certain to be
them, and report the result as owner_face_confidence. A low value there
weakens how firmly every vision reading is held, rather than pretending the
person fits worse than they do.
A screenshot of the profile page would show much the same thing, but that page needs a logged-in browser to render at all, while these thumbnails have already been fetched and paid for.
Reading the confidence
Every attribute carries two numbers, never one: match is how well the evidence agrees, certainty is how far that evidence can be trusted. A model that reports a single "85%" has silently multiplied them and thrown away which one was weak.
Certainty is capped per attribute and per source, so the system cannot
overclaim. Hair colour read off one avatar caps at 0.45; read off several
daylight posts, 0.80. Country from Instagram's own "account based in" reaches
0.95. Height caps at 0.15 — a photograph carries no scale reference — and
height, ethnicity and build are advisory: reported, never allowed to move a
ranking, and rejected outright if you mark them required.
Unknown is not "no". An attribute nobody could observe lowers coverage, not
match, and the ranking shrinks toward the prior by how little was verified — so
a 0.9 scored on two observed attributes loses to a 0.75 on six. Anything labelled
unverified scored well on too little to act on.
Results are for public accounts. Private ones are dropped at the gate because
they cannot be verified. Nobody under 18 is ever returned: age is read from a
stated birth year and from Instagram's join date, the bottom of that estimate
decides, and the check runs when age first becomes readable and again at every
exit - an audit found the original gate-only version protected nothing, because
the gate runs before any age has been read. Every candidate keeps full provenance — which
probes found them, and what each conclusion rests on. Search jobs live in
searches/ and are gitignored: they hold other people's profiles and photos.
Staying unblocked
instagrapi drives the private API that the phone app uses. Instagram detects and blocks automated behaviour, and the account it blocks is yours — so:
Sessions are cached in
session.jsonand reused. Logging in from scratch repeatedly is the single fastest way to get flagged. Keep that file.Requests are spaced out by a random
INSTAGRAM_DELAY_MIN–INSTAGRAM_DELAY_MAXsecond pause. Raise it if Instagram starts asking you to wait.Back off on warnings. "Please wait a few minutes" and "action blocked" mean stop, not retry. The tools say so in their error messages.
Bulk reads are risky. Pulling thousands of followers in one go looks nothing like a human using the app.
Use a throwaway or secondary account if you are experimenting.
Layout
File | Contains |
| The 49 tool definitions |
| What a persona is, and the confidence maths |
| Reading a persona off a profile, free and offline |
| Given names to a gender prior, offline |
| The recall channels candidates come from |
| A persona search as a resumable job on disk |
| Candidate pictures composed into one judgeable sheet |
| Login, session persistence, the write guard, threading |
| Compact JSON views of instagrapi's models |
| Instagram exceptions turned into actionable advice |
| Offline check: schemas, guards, serializers |
.env and session.json hold credentials and live auth cookies, and searches/
holds other people's profiles and photos. All three are gitignored — keep them
that way.
Available Tools
49 toolsinstagram_account_aboutARead-onlyIdempotent
Read Instagram's own "About this account" panel: country, join date, past handles.
The country field is Instagram's own answer to where an account is based, which makes it the single most trustworthy location signal a profile can carry - worth far more than anything written in a bio. The join date and any former usernames are useful for spotting accounts that are newer, or more recycled, than they present themselves as.
Args: username: The handle to look up. user_id: The numeric id, if you already have it.
Returns: username, country, joined, former_usernames, and a note when Instagram returned the panel without a country. Fields it does not return are omitted.
Inputs: user_id, username. Returns: object
instagram_account_infoARead-onlyIdempotent
Get the profile of the logged-in account, including its private fields.
Returns the signed-in user's own details (email, phone, gender and birthday are visible here but not on other people's profiles). Use instagram_get_user for anyone else.
Returns: An account object: user_id, username, full_name, biography, external_url, is_private, is_verified, is_business, email, phone_number, gender.
Inputs: no named parameters. Returns: object
instagram_build_style_profileAIdempotent
Learn how you write by measuring your own sent DMs, and cache the result.
Reads your conversations, keeps only the messages you sent, and measures the habits that make writing recognisable: message length, capitalisation, punctuation, emoji, how you spell laughter, shorthand, language mixing, and whether you send bursts of short messages. It also records how your voice shifts per contact, since nobody writes to their mother the way they write to a friend.
Run once to set up, then again occasionally to refresh. The profile is saved locally and read by instagram_prepare_dm. Nothing is sent to Instagram.
Args: thread_count: How many conversations to sample. messages_per_thread: How many messages to read from each.
Returns: messages_analyzed, threads_analyzed, style_rules[] (plain-language instructions for imitating the voice), voice (the raw measurements), samples[] (real sent messages), contacts (per-person breakdown), and saved_to (the cache path).
Inputs: thread_count, messages_per_thread. Returns: object
instagram_comment_mediaA
Post a comment on a post, or a reply to an existing comment.
Publicly visible immediately. Confirm the wording with the person you are working for first. Requires INSTAGRAM_ALLOW_WRITES=true.
Args: media: A post URL, shortcode or media id. text: What to say. replied_to_comment_id: Reply to this comment instead of the post.
Returns: posted (bool) and comment: comment_id, text, author, created_at.
Inputs: text (required), media (required), replied_to_comment_id. Returns: object
instagram_delete_mediaADestructive
Permanently delete one of the logged-in account's own posts.
This cannot be undone and Instagram keeps no copy you can restore from. Always confirm the exact post with the person you are working for first - read it back with instagram_get_media and check it is theirs. Requires INSTAGRAM_ALLOW_WRITES=true.
Args: media: The post URL, shortcode or media id to delete.
Returns: deleted (bool) and media (the reference acted on).
Inputs: media (required). Returns: object
instagram_download_mediaAIdempotent
Download a post's photo, video, or every item in an album, to local disk.
Writes files to the machine running this server, not to Instagram, so it is safe in read-only mode. Albums produce one file per item.
Args: media: A post URL, shortcode or media id. folder: Where to write the files.
Returns: type (photo/video/reel/igtv/album), file_count and files[] with the absolute paths written.
Inputs: media (required), folder. Returns: object
instagram_find_personARead-onlyIdempotent
Find who to message, searching your existing conversations before all of Instagram.
Use this when a person is referred to by first name only, or when you are not sure which account is meant. People you already talk to rank first and come back with a thread_id you can pass straight to instagram_prepare_dm.
Args: query: The name or handle to look for. limit: How many matches to return.
Returns: count and matches[]: user_id, username, full_name, is_verified, thread_id (null if you have never messaged them), has_conversation, is_group.
Inputs: query (required), limit. Returns: object
instagram_follow_userAIdempotent
Follow a user as the logged-in account.
For private accounts this sends a follow request instead. Requires INSTAGRAM_ALLOW_WRITES=true.
Args: username: The handle to follow. user_id: The numeric id, if you already have it.
Returns: followed (bool) and user_id.
Inputs: user_id, username. Returns: object
instagram_get_direct_threadARead-onlyIdempotent
Read the messages in one direct-message conversation, newest first.
Shared posts, links and attachments are summarised rather than reproduced.
Args: thread_id: Which conversation to read. amount: How many messages to fetch.
Returns: thread_id, title, is_group, participants[], last_activity_at, unread and messages[]: message_id, sender_id, sent_at, item_type, is_sent_by_you, text, shared_post, link, attachment.
Inputs: thread_id (required), amount. Returns: object
instagram_get_followersARead-onlyIdempotent
List the accounts that follow a user, newest follower first.
Only works for your own account, public accounts, and private accounts you follow. Fetching thousands of followers is slow and is the fastest way to get an account rate limited - ask for the smallest number that answers the question.
Args: username: The handle whose followers to list. user_id: The numeric id, if you already have it. amount: How many followers to fetch.
Returns: count, requested, possibly_more (bool) and users[]: user_id, username, full_name, is_private, is_verified.
Inputs: amount, user_id, username. Returns: object
instagram_get_followingARead-onlyIdempotent
List the accounts a user follows.
Same visibility rules and rate-limit caution as instagram_get_followers.
Args: username: The handle whose following list to read. user_id: The numeric id, if you already have it. amount: How many accounts to fetch.
Returns: count, requested, possibly_more (bool) and users[]: user_id, username, full_name, is_private, is_verified.
Inputs: amount, user_id, username. Returns: object
instagram_get_hashtag_infoARead-onlyIdempotent
Get a hashtag's total post count.
Use this to size a hashtag before pulling posts from it.
Args: name: The hashtag, with or without a leading #.
Returns: id, name, media_count (int) and url.
Inputs: name (required). Returns: object
instagram_get_hashtag_mediasARead-onlyIdempotent
List posts carrying a hashtag, either the top posts or the most recent.
The main discovery tool: use 'top' to see what performs well on a tag and 'recent' to see current activity.
Args: name: The hashtag to read. sort: Ranked ('top') or chronological ('recent'). amount: How many posts to fetch.
Returns: hashtag (str), sort (str), count and medias[]: media_id, code, url, type, taken_at, author, caption, like_count, comment_count.
Inputs: name (required), sort, amount. Returns: object
instagram_get_location_mediasARead-onlyIdempotent
List posts tagged at a place.
Args: location_id: The place id from instagram_search_locations. sort: Ranked ('top') or chronological ('recent'). amount: How many posts to fetch.
Returns: location_id, sort, count and medias[] as in instagram_get_user_medias.
Inputs: location_id (required), sort, amount. Returns: object
instagram_get_mediaARead-onlyIdempotent
Get everything about one post, including media URLs and tagged users.
Use after a listing tool when you need the full caption, the downloadable photo/video URLs, or the contents of an album.
Args: media: A post URL, a shortcode, or a numeric media id.
Returns: media_id, code, url, type, taken_at, author, caption, like_count, comment_count, view_count, location, thumbnail_url, video_url, video_duration, comments_disabled, tagged_users[] and album_items[] for multi-photo posts.
Inputs: media (required). Returns: object
instagram_get_media_commentsARead-onlyIdempotent
Read the comments on a post.
Returns top-level comments and replies as a flat list; a comment's replied_to_comment_id tells you what it is answering.
Args: media: A post URL, shortcode or media id. amount: How many comments to fetch.
Returns: count, requested, possibly_more and comments[]: comment_id, text, author, created_at, like_count, replied_to_comment_id.
Inputs: media (required), amount. Returns: object
instagram_get_media_likersARead-onlyIdempotent
List the accounts that liked a post.
Instagram returns only a recent window of likers, not everyone, so the count here will not match the post's like_count on popular posts.
Args: media: A post URL, shortcode or media id. amount: How many likers to keep.
Returns: count and users[]: user_id, username, full_name, is_private, is_verified.
Inputs: media (required), amount. Returns: object
instagram_get_style_profileARead-onlyIdempotent
Read the cached description of how you write, without contacting Instagram.
Instant and free, so prefer it over rebuilding. If no profile exists yet it says so and you should call instagram_build_style_profile once.
Returns: exists (bool), and when present: generated_at, messages_analyzed, style_rules[], voice, samples[].
Inputs: no named parameters. Returns: object
instagram_get_timeline_feedARead-onlyIdempotent
Read the logged-in account's home timeline - posts from accounts it follows.
This is the feed the app opens on. Sponsored items are skipped.
Args: amount: How many posts to return.
Returns: count and medias[]: media_id, code, url, type, taken_at, author, caption, like_count, comment_count.
Inputs: amount. Returns: object
instagram_get_userARead-onlyIdempotent
Get a user's full public profile: counts, biography, category and links.
Use this to resolve a username to a user_id, to check whether an account is private before trying to read its posts, or to read follower/following/post counts. For the posts themselves use instagram_get_user_medias.
Args: username: The handle to look up. user_id: The numeric id, if you already have it.
Returns: user_id, username, full_name, url, biography, external_url, follower_count, following_count, media_count, is_private, is_verified, is_business, category, public_email, profile_pic_url. Fields Instagram does not return are omitted.
Inputs: user_id, username. Returns: object
instagram_get_user_mediasARead-onlyIdempotent
List a user's posts (photos, videos, reels and albums), newest first.
This is the main way to read someone's feed. Captions are truncated; call instagram_get_media on a single post for the full record and media URLs.
Args: username: The handle whose posts to list. user_id: The numeric id, if you already have it. amount: How many posts to fetch.
Returns: count, requested, possibly_more and medias[]: media_id, code, url, type (photo/video/reel/igtv/album), taken_at, author, caption, like_count, comment_count, view_count and location where present.
Inputs: amount, user_id, username. Returns: object
instagram_get_user_storiesARead-onlyIdempotent
Read a user's currently active stories.
Stories vanish after 24 hours, so an empty list usually means the user has not posted today rather than that something failed. Viewing stories this way does not mark them as seen.
Args: username: The handle whose stories to read. user_id: The numeric id, if you already have it. amount: How many stories to fetch.
Returns: count and stories[]: story_id, type (photo/video), taken_at, author, video_duration, mentions, links, thumbnail_url, video_url.
Inputs: amount, user_id, username. Returns: object
instagram_like_mediaAIdempotent
Like a post as the logged-in account.
Requires INSTAGRAM_ALLOW_WRITES=true. Liking in bursts is the quickest way to trigger an Instagram action block - space these out.
Args: media: A post URL, shortcode or media id.
Returns: liked (bool) and media (the post URL or reference acted on).
Inputs: media (required). Returns: object
instagram_list_direct_threadsARead-onlyIdempotent
List direct-message conversations in the inbox.
Gives you the thread_id needed by instagram_get_direct_thread and instagram_send_direct_message, plus a preview of the latest message.
Args: amount: How many conversations to fetch. only_unread: Restrict to conversations with unread messages.
Returns: count and threads[]: thread_id, title, is_group, participants[], last_activity_at, unread, pending, muted and last_message.
Inputs: amount, only_unread. Returns: object
instagram_loginAIdempotent
Authenticate with Instagram using the credentials in the server's .env.
Login is automatic on first use, so call this only to recover from an expired session or to supply a two-factor/challenge code. The session is cached on disk and reused, which matters: repeatedly logging in from scratch is what makes Instagram flag an account.
Args: verification_code: The code Instagram asked for, if any. force: Re-authenticate even if this process already holds a session.
Returns: logged_in (bool), logged_in_as (str), summary (str) describing whether a cached session was reused, and session_file (str) where it was saved.
Inputs: force, verification_code. Returns: object
instagram_login_statusARead-onlyIdempotent
Report whether an Instagram session is active and how the server is configured.
Never logs in and never contacts Instagram, so it is the safe first call when something is not working. Use it to check which account is in use, whether write actions are permitted, and whether credentials are present at all.
Returns: logged_in (bool), logged_in_as (str|null), summary (str), and a configuration object reporting which credentials are set (never their values), the write-mode flag, the session cache path and the delay range.
Inputs: no named parameters. Returns: object
instagram_prepare_dmARead-onlyIdempotent
Get everything needed to draft a DM in one call: who, the conversation so far, and your voice.
This is the tool to reach for when asked to write or reply to someone on Instagram. It bundles the recent back-and-forth with the measured rules of how you write - both in general and specifically to this person - so a draft can match your voice instead of guessing at it.
It only gathers context. Nothing is sent until instagram_send_direct_message is called, which is deliberate: the draft should be shown to you first.
If the person is ambiguous it returns the candidates instead of guessing.
Args: person: Name or handle of who to message. thread_id: Or an existing conversation id. history: How many recent messages to include.
Returns: Either needs_disambiguation with candidates[], or: contact, thread_id, conversation[] (chronological, each {from: 'you'|'them', text, at}), your_voice {rules[], samples[], measurements}, with_this_person {my_message_count, burst_rate, my_samples[]}, and last_message_from.
Inputs: person, history, thread_id. Returns: object
instagram_search_enrichARead-onlyIdempotent
Fetch full profiles, posts and country for the most promising candidates.
This is the expensive stage - roughly three API calls per candidate, so a limit of 40 is around two hundred seconds of deliberate delay before it returns - and it is the one that gets accounts rate limited, so it works on a ranked subset rather than the whole pool. Progress is saved every few candidates and the lock is released between them, so an interruption costs only the candidate in flight and the server stays responsive throughout. Candidates found on several channels go first, since corroboration is the only precision signal available before a profile has been read.
Fetches are best-effort: a candidate whose profile fails is recorded and skipped rather than ending the batch. Nothing already fetched is fetched again, so calling this repeatedly walks further down the pool.
Args: search_id: The search to enrich. limit: How many candidates to fetch. posts_per_user: How many recent posts to read each. include_about: Whether to read the account's country.
Returns: enriched, failed, api_calls, failures[] and next_step.
Inputs: search_id (required), limit, include_about, posts_per_user. Returns: object
instagram_search_expandARead-onlyIdempotent
Grow the pool by asking Instagram for accounts similar to your best ones.
This is the highest-yield stage in the whole search. Keyword probes find a foothold; this walks Instagram's own similarity graph outward from it, which returns candidates at far better precision than any search box can. Run it once the pool has a few good accounts in it, and again after scoring, when the seeds it picks are proven matches rather than guesses.
Args: search_id: The search to expand. seed_count: How many top candidates to use as seeds. usernames: Explicit seeds, overriding the pool's own ranking.
Returns: seeds_used, added, pool_size, api_calls, errors[] and next_step.
Inputs: search_id (required), usernames, seed_count. Returns: object
instagram_search_gateARead-onlyIdempotent
Cut the pool down using only data already fetched. Costs nothing.
Run it straight after recall, and again after enrichment - the first pass can only see privacy and handles, while the second can see follower counts and bios. The under-18 floor does not depend on this: it is applied the moment age becomes readable and again at every exit, so no ordering of stages can let a minor through.
Every drop is counted by reason, so a gate that removes too much can be loosened deliberately rather than guessed at.
Args: search_id: The search to filter. exclude_private: Drop private accounts. exclude_shops: Drop apparent businesses. min_media: Minimum post count. follower_min: Follower floor. follower_max: Follower ceiling. max_pool: Maximum candidates to keep.
Returns: kept, dropped, reasons (a count per drop reason) and next_step.
Inputs: search_id (required), max_pool, min_media, follower_max, +3 more. Returns: object
instagram_search_judgeARead-onlyIdempotent
Record what you saw in bios and images, and rescore against the persona.
Report observations, not verdicts: say the hair was 'brown', not that it scored 0.2 against a persona wanting blonde. Whether an observation satisfies the persona is decided in one place, so judgments cannot grade themselves and a mismatch cannot be smuggled in as a good score.
Naming the source matters: several images agreeing ('vision_multi') is a stronger measurement than one avatar ('vision_single'), and each carries a different ceiling. Use 'strength' below 1.0 when a reading is genuinely uncertain, and owner_face_confidence when it is unclear which face belongs to the account - both make the reading less certain rather than pretending it fits worse than it does.
Args: search_id: The search to update. judgments: Per-candidate attribute readings.
Returns: applied, rejected, unknown_candidates, problems[] and next_step.
Inputs: judgments (required), search_id (required). Returns: object
instagram_search_listARead-onlyIdempotent
List every persona search on disk, most recently touched first.
Reads local files only, so it never contacts Instagram. Use it to pick up a search that was interrupted - nothing already fetched needs fetching again.
Returns: count and searches[]: search_id, label, stage, candidates, api_calls, updated_at.
Inputs: no named parameters. Returns: object
instagram_search_locationsARead-onlyIdempotent
Find Instagram place pages by name, to get a location_id.
Feed instagram_get_location_medias with the location_id you get back.
Args: query: The place name to search for. amount: How many places to keep.
Returns: count and locations[]: location_id, name, address, city, lat, lng.
Inputs: query (required), amount. Returns: object
instagram_search_postsARead-onlyIdempotent
Search posts by keyword, the way the app's search results tab does.
Unlike hashtag lookup this matches captions and Instagram's own topic modelling, so it works for phrases nobody tags. Mostly useful as a way to reach the accounts behind the posts.
Args: query: The phrase to search for. amount: How many posts to fetch.
Returns: query, count and medias[]: media_id, code, url, type, taken_at, author, caption, like_count, comment_count.
Inputs: query (required), amount. Returns: object
instagram_search_recallARead-onlyIdempotent
Sweep Instagram for candidates and add them to the search pool.
Channels: accounts (handle/name/bio text, paginated), hashtags (post authors), places (authors of geotagged posts - the strongest location probe), posts (keyword search), seeds (accounts similar to one you name), followers, likers, commenters, co_tagged (who someone is photographed with).
Fire many cheap probes rather than one careful one. Precision per probe is poor by design; what matters is that candidates surfacing on several unrelated channels rank higher, and that costs nothing extra. Channels fail independently, so a rate limit on one does not lose the others.
Repeatable - call again with more probes to widen the pool.
Args: search_id: The search to add to. probes: Channel names mapped to lists of probe arguments.
Returns: pool_size, corroborated (found by more than one channel), api_calls, channels[] (per-probe counts), errors[] and next_step.
Inputs: probes (required), search_id (required). Returns: object
instagram_search_resultsARead-onlyIdempotent
The ranked answer, with every attribute's evidence attached.
Read two numbers, not one. ranked_score is the ranking; coverage is
how much of the persona was actually observable on that account. A high raw
score over two observed attributes is worth less than a good one over six,
and the ranking already reflects that - anything labelled 'unverified' scored
well on too little to trust.
Attributes marked 'unobserved' were not visible, which is not the same as not matching. Attributes marked advisory are reported but were never allowed to affect the ranking.
Args: search_id: The search to read. limit: How many profiles to return.
Returns: count, persona, results[] (rank, username, url, confidence, ranked_score, coverage, found_via, attributes with evidence) and the search's total api_calls.
Inputs: search_id (required), limit. Returns: object
instagram_search_shortlistAIdempotent
Get the best candidates packaged for judging, optionally with their images.
Each bundle says explicitly what is still unobserved and what was observed only weakly - those are the reasons to spend a look, and judging anything else is wasted effort.
With download_images, each candidate's profile picture and recent post thumbnails are fetched and composed into a single numbered contact_sheet on the machine running this server. Read that one image rather than the tiles individually: it is a twelfth of the attention, the numbers let a judgement cite the tile it came from, and seeing every picture side by side is what makes the hard question answerable.
That question is which face is the account holder. Feeds are full of friends, partners and clients, so before judging appearance find the face that recurs across the tiles and check it against the one marked 'avatar', which is the only picture certain to be them. Report the result as owner_face_confidence - a judgement made on the wrong face is worse than none, because it arrives sounding just as certain as a right one.
Args: search_id: The search to shortlist from. limit: How many candidates to prepare. download_images: Whether to fetch images to local disk. images_per_user: How many images per candidate.
Returns: count, candidates[] (each with biography, signals, needs_judging, weakly_observed and images[]) and how to report judgments back.
Inputs: search_id (required), limit, download_images, images_per_user. Returns: object
instagram_search_signalsARead-onlyIdempotent
Read every enriched candidate against the persona, for free.
Contacts nothing and calls no model. It measures what is already on disk: gender from the given name and any stated pronouns, city from a recency-weighted cluster of where posts were geotagged, country from Instagram's own answer, language from caption wording, niche from tags and category, and age from any birth year given away.
It resolves everything except appearance, which no free signal can reach - so run it before spending anything on images, and let vision see only what survives it.
Args: search_id: The search to analyse.
Returns: scored, confidence_breakdown, top[] (a preview of the ranking) and next_step.
Inputs: search_id (required). Returns: object
instagram_search_startARead-onlyIdempotent
Begin a persona search and get back a search_id to drive it with.
Nothing is fetched here. This validates the persona, tells you how certain each attribute could ever be, and opens a job on disk that survives crashes and rate limits - a full search is hundreds of calls over many minutes, so it is run stage by stage rather than in one blocking call.
Scorable attributes: country, city, language, niche, gender, age_band, hair, build, follower_range, engagement, account_type, height, ethnicity. Some are advisory - they are reported but never allowed to move the ranking, because they cannot be read off a profile reliably enough to reject anyone on.
After this, call instagram_search_recall with a probe plan.
Args: persona: The attributes to search for, with optional weights. label: A human-readable name for the search.
Returns: search_id, persona (compiled, with max_certainty per attribute) and next_step.
Inputs: persona (required), label. Returns: object
instagram_search_usersARead-onlyIdempotent
Search Instagram for users by handle or display name.
Returns the same ranked list the app's search box shows. Results are shallow; follow up with instagram_get_user for counts and biography.
Args: query: What to search for. amount: How many results to keep.
Returns: count (int) and users[]: user_id, username, full_name, is_private, is_verified.
Inputs: query (required), amount. Returns: object
instagram_send_direct_messageA
Send a direct message, either into an existing thread or to new recipients.
Sends immediately and cannot be undone from here. Confirm the exact recipient and wording with the person you are working for before calling this. Requires INSTAGRAM_ALLOW_WRITES=true.
Args: text: The message to send. thread_id: Reply into this conversation. usernames: Or start/continue a conversation with these handles. user_ids: Or the same recipients by numeric id.
Returns: sent (bool), message_id, thread_id, sent_at and text.
Inputs: text (required), user_ids, thread_id, usernames. Returns: object
instagram_similar_accountsARead-onlyIdempotent
List the accounts Instagram itself considers similar to one you name.
This reads the same "Suggested for you" graph the app shows under a profile, built from co-follow behaviour Instagram has already modelled. It is by far the highest-precision way to find more accounts like one you already like - far better than searching words - so the usual pattern is to find one good example by any means and then chain outward from it.
Instagram refuses chaining for some accounts, mostly private or recently flagged ones; a second, older endpoint is tried before giving up.
Args: username: The handle to find lookalikes for. user_id: The numeric id, if you already have it. amount: How many accounts to keep.
Returns: seed (the account asked about), count and users[]: user_id, username, full_name, is_private, is_verified.
Inputs: amount, user_id, username. Returns: object
instagram_unfollow_userAIdempotent
Unfollow a user as the logged-in account.
Requires INSTAGRAM_ALLOW_WRITES=true.
Args: username: The handle to unfollow. user_id: The numeric id, if you already have it.
Returns: unfollowed (bool) and user_id.
Inputs: user_id, username. Returns: object
instagram_unlike_mediaAIdempotent
Remove the logged-in account's like from a post.
Requires INSTAGRAM_ALLOW_WRITES=true.
Args: media: A post URL, shortcode or media id.
Returns: unliked (bool) and media (the post reference acted on).
Inputs: media (required). Returns: object
instagram_upload_albumA
Publish several photos or videos as one carousel post.
Instagram allows between 2 and 10 items. Requires INSTAGRAM_ALLOW_WRITES=true.
Args: paths: The files to publish, in order. caption: The caption to publish with them.
Returns: posted (bool), item_count and media: media_id, code, url, type, caption.
Inputs: paths (required), caption. Returns: object
instagram_upload_photoA
Publish a photo to the feed.
Instagram accepts JPEG; other formats are converted first. This posts publicly and immediately - confirm the file and caption with the person you are working for. Requires INSTAGRAM_ALLOW_WRITES=true.
Args: path: The image file to publish. caption: The caption to publish with it.
Returns: posted (bool) and media: media_id, code, url, type, taken_at, caption.
Inputs: path (required), caption. Returns: object
instagram_upload_reelA
Publish a reel.
Expects vertical 9:16 video. Requires INSTAGRAM_ALLOW_WRITES=true.
Args: path: The MP4 to publish as a reel. caption: The caption to publish with it. thumbnail: Optional cover image.
Returns: posted (bool) and media: media_id, code, url, type, taken_at, caption.
Inputs: path (required), caption, thumbnail. Returns: object
instagram_upload_storyA
Publish a photo or video to your story, where it lasts 24 hours.
The file type is detected from its extension. Requires INSTAGRAM_ALLOW_WRITES=true.
Args: path: The image or video to publish. caption: Optional caption stored with the story.
Returns: posted (bool) and story: story_id, type, taken_at, author.
Inputs: path (required), caption. Returns: object
instagram_upload_videoA
Publish a video to the feed.
For vertical short-form content use instagram_upload_reel instead - reels get different distribution. Requires INSTAGRAM_ALLOW_WRITES=true.
Args: path: The MP4 to publish. caption: The caption to publish with it. thumbnail: Optional cover image.
Returns: posted (bool) and media: media_id, code, url, type, taken_at, caption.
Inputs: path (required), caption, thumbnail. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 49 tools
Most tools have clearly distinct purposes, but there is some overlap between instagram_search_posts and instagram_get_hashtag_medias (both return posts) and between instagram_find_person and instagram_search_users (both find users). The descriptions clarify the intended use cases, so ambiguity is limited.
All tools follow a consistent 'instagram_' prefix with a verb_noun pattern (e.g., instagram_get_user_medias, instagram_upload_photo, instagram_search_recall). This makes the API predictable and easy to navigate, with no mixed conventions or vague verbs.
At 49 tools, this exceeds the '25+' threshold for too many. While the server covers a wide range of Instagram features, including a complex persona search pipeline, the sheer number makes the surface overwhelming and likely to cause selection fatigue for agents.
The tool set covers the core lifecycle well: retrieval (users, media, stories, comments, likes, hashtags, locations), engagement (like/unlike, comment, follow/unfollow, direct messages), publishing (photo, video, reel, album, story, delete), and account management. Minor gaps exist (e.g., no ability to edit an existing post or delete a comment), but they are not critical for most workflows.
Maintenance
Related MCP Connectors
Instagram for AI agents: publish, read comments and DMs, insights, and engage from your account.
Instagram MCP for DM and comment automation, AI Agent and content publishing via Meta's official API
Instagram and Facebook Pages for AI agents: publish, comments, DM by keyword, inbox, insights.
Instagram search and posts for AI agents, with images and videos AI-parsed to text.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables LLMs to interact with Instagram through a comprehensive toolkit for account management, content creation, messaging, social graph analysis, and content discovery.13-
- FlicenseBqualityDmaintenanceEnables AI agents to control Instagram accounts programmatically, supporting profile management, media interaction, direct messaging, and follower management.132-

@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.62691 npm15MIT- 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.-