Skip to main content
Glama
instagram-mcp

instagram-mcp

by osAlhaddad1

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 .env

Then 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.py

Related 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=true

Restart 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

instagram_prepare_dm, instagram_find_person, instagram_build_style_profile, instagram_get_style_profile

Persona search

instagram_search_start, instagram_search_recall, instagram_search_gate, instagram_search_expand, instagram_search_enrich, instagram_search_signals, instagram_search_shortlist, instagram_search_judge, instagram_search_results, instagram_search_list

Session

instagram_login_status, instagram_login, instagram_account_info

Users

instagram_get_user, instagram_search_users, instagram_get_followers, instagram_get_following, instagram_get_user_medias, instagram_get_user_stories

Posts

instagram_get_media, instagram_get_media_comments, instagram_get_media_likers, instagram_download_media

Discovery

instagram_get_timeline_feed, instagram_get_hashtag_info, instagram_get_hashtag_medias, instagram_search_locations, instagram_get_location_medias, instagram_search_posts, instagram_similar_accounts, instagram_account_about

Direct messages

instagram_list_direct_threads, instagram_get_direct_thread, instagram_send_direct_message *

Engagement

instagram_like_media *, instagram_unlike_media *, instagram_comment_media *, instagram_follow_user *, instagram_unfollow_user *

Publishing

instagram_upload_photo *, instagram_upload_video *, instagram_upload_reel *, instagram_upload_album *, instagram_upload_story *, instagram_delete_media *

* 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 attached

What 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.json and 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_MAX second 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

instagram_mcp/server.py

The 49 tool definitions

instagram_mcp/persona.py

What a persona is, and the confidence maths

instagram_mcp/signals.py

Reading a persona off a profile, free and offline

instagram_mcp/names.py

Given names to a gender prior, offline

instagram_mcp/discovery.py

The recall channels candidates come from

instagram_mcp/search.py

A persona search as a resumable job on disk

instagram_mcp/sheets.py

Candidate pictures composed into one judgeable sheet

instagram_mcp/client.py

Login, session persistence, the write guard, threading

instagram_mcp/serialize.py

Compact JSON views of instagrapi's models

instagram_mcp/errors.py

Instagram exceptions turned into actionable advice

smoke_test.py

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 tools
instagram_account_aboutA
Read-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_infoA
Read-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_profileA
Idempotent

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_mediaA
Destructive

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_mediaA
Idempotent

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_personA
Read-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_userA
Idempotent

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_threadA
Read-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_followersA
Read-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_followingA
Read-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_infoA
Read-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_mediasA
Read-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_mediasA
Read-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_mediaA
Read-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_commentsA
Read-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_likersA
Read-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_profileA
Read-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_feedA
Read-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_userA
Read-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_mediasA
Read-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_storiesA
Read-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_mediaA
Idempotent

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_threadsA
Read-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_loginA
Idempotent

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_statusA
Read-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_dmA
Read-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_enrichA
Read-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_expandA
Read-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_gateA
Read-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_judgeA
Read-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_listA
Read-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_locationsA
Read-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_postsA
Read-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_recallA
Read-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_resultsA
Read-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_shortlistA
Idempotent

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_signalsA
Read-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_startA
Read-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_usersA
Read-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_accountsA
Read-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_userA
Idempotent

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_mediaA
Idempotent

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

    A3.9/5.0

    Scored across 49 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • 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.
      62
      691 npm
      15
      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.
      -