instagram-mcp

instagrapi — Instagramの非公開モバイルAPI — を、エージェントが呼び出せる49本のツールとして公開するMCPサーバーです。

読み取りは初期状態で有効です。アカウントに変更を加える操作（投稿、いいね、フォロー、コメント、DM、削除）は、明示的に書き込みを有効にするまで拒否されます。

Setup

cp .env.example .env

その後、.env にユーザー名とパスワード、または、すでにログイン済みのブラウザからコピーした**sessionidクッキー**のどちらかを記入します（DevTools → Application → Cookies → instagram.com）。sessionid の方法のほうがログインチャレンジが発生しにくいです。

アカウントが2要素認証を使っている場合、認証アプリの「セットアップキー」を INSTAGRAM_TOTP_SEED に貼り付けると、コードが自動生成されます。それ以外の場合、Instagram がコードを求めてきたら verification_code を指定して instagram_login を呼び出してください。

Instagram に接続せずにインストールを確認する:

.venv/Scripts/python smoke_test.py

Related MCP server: Instagram MCP Server

サーバーの登録

このプロジェクトでは ../.mcp.json に登録済みです。別の場所で使うには:

claude mcp add instagram -- "C:\Users\osami\OneDrive\Documents\GitHub\ayham project 2\instagram-mcp\.venv\Scripts\instagram-mcp.exe"

実行ファイルはどのディレクトリからでも動作します。常に .env を読み込み、このREADMEの隣に session.json を書き込みます。

書き込み操作を有効にする

INSTAGRAM_ALLOW_WRITES=true

その後、サーバーを再起動してください。この値が false の間、書き込みツールは何も実行せず、説明を示して失敗します。そのため、読み取り専用ツールは引き続き使用できます。

ツール

* は INSTAGRAM_ALLOW_WRITES=true が必要です。

ユーザーは username または user_id で指定します。投稿は media 引数で指定し、投稿URL、ショートコード、または数字のメディアIDを受け付けます。

自分の文体でDMを書く

それがこのサーバーの主目的です。モデルにメッセージを書かせると、正しく書こうとします。句読点も大文字も丁寧さもちゃんとした文になります。そして、あなたを知っている人には、それだけで代筆だと一発で分かります。

そこで instagram_build_style_profile は、あなたが実際に送ったDMから、あなたの実際の書き方を計測します: メッセージの長さ、大文字の使い方、文末の句読点、絵文字の使用率、どの絵文字を使うか、笑いのかき方、略語、言語の交ざり方、それから、まとまったメッセージを1通送らずに短いメッセージを連投するかどうか。これをグローバルにも、コンタクトごとにも記録します。誰も、最も親しい友人に書くような書き方を、自分の母に宛ててはのでしないからです。

一度実行してください:

.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])"

以後は、instagram_prepare_dm(person="sarah") を呼ぶだけで、直近の会話、計測したあなたの文体ルール、その相手に向けたあなたの書き方のサンプルがまとめて返ってきます。この1回の呼び出しが下書き作成のためのすべてのインターフェースです。生のスレッド用ツールを手でつなぎ合わせる必要はありません。

プロフィールは style_profile.json にキャッシュされ、Instagram に送信されることはありません。書き方が漂っていくので、たまに更新してください。

スキル

~/.claude/skills/instagram-dm/SKILL.md が、ふだんの会話の中でワークフロー全体を動かします — 「Ahmedに返信して」「彼女に何と返そう」「インスタのメッセージを確認して」など。相手を探し、あなたの文体を読み込み、下書きし、実際に送信する前にあなたの認める保留します。

あなたがまず正確な文言そのものを目で見てからでなければ、何も送信されません。

ペルソナに一致する人を見つける

それがこのサーバーのもうひとつの用途です。あなたがある人を説明すると — 女性、アムステルダム、フィットネス、20代半ば、ブロンド — その属性ごとの「自信度付き」で、順位付けされたプロフィールが返ってきます。

問題は、Instagramにはそのようなもののためのインデックスが存在しないことです。Instagramがインデックスしているのは、ハンドル名と名前のテキスト、ハッシュタグ、場所のジオコーティング、フォローグラフの4つだけです。ペルソナはそのどれでもありません。したがって、各属性は、その4つのいずれかに対するプローブに加工されるか、得られた結果から後から推測されたもの。つまり、これはクエリーではなく、再現性与衡量を交換するファネル（漏斗）です。

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

それを成立させているのが instagram_similar_accounts です。Instagram自身の「おすすめ」グラフを読みます。Instagramはすでに共同フォローの振る舞いをモデル化しており、そこから作られるグラフです。1つ良い一致を見つけたならば、そこから外側にずっと連鎖していくのが、キーワード検索よりもはるかに勝っています。だからこそ、テキストとハッシュタグのプローブは、主にその最初の足がかりを見つけるために存在しているのです。

もう一つ知っておくべきことがあります。「別の場所」という意味で、Instagramの city フィールドは、ほぼ常に null で、まれに誤っています。実際のプローブでは、エジプト・アレンデリア座標を持つ「Hollanda」という名前の場所が返ってきました。また、場所が表示される 姓名（プレイスネーム） 分断されがちで、1つの都市が「Amsterdam, Netherlands」「Amsterdam Canal District」「Red Light District, Amsterdam」「Amsterdam Canal River」としてばらばらに届きます。しかし、座標は常に存在するため、ジオタグは名前ではなく位置でクラスタリングされます。表記ゆれは1つに統合され、誤って付与されたラベルがあれば、その候補は自動的にクラスタから除外されます。

当初の設計が頼りにしていたことのひとつは、存在しないことが後から分かりました。Instagramは写真に対して代替テキストを生成します（「1人の人物、ブロンドの髪、立っている」といった表現）。これがあれば、すべての投稿に対して無料の粗い画像認識を手に入れられたはずですが、これはWebクライアントにしか公開されておらず、実プローブ32投稿のすべてで空だったのです。したがって、見た目を判断するには実際の画像を実際に「見る」コストがかかる。上限は、その現実を無理に隠さず反映しています。

検索は関数呼び出しではなく、ディスク上に常駐するジョブです。実際の本番検索は、Instagram にレート制限されるアカウントで数百回のAPIコールを10〜20分間もかけて行うため、段階的に実行し、クラッシュしても残り、プローブ計画を修正しない場合、300ではなく20コールで修正できます。

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)

見た目を判定する

見た目は、追加コストのかからない信号では決して届かない唯一の項目なので、実際に目視するしかありません。instagram_search_shortlist(download_images=true) は、各候補者のプロフィール画像と最近のサムネイルを取得し、バラバラのファイルではなく、単一の番号付きコンタクトシートにまとめます。

これは単に見た目が整うだけではありません。注意力が12分の1で済み、番号により、判定者が自分の判断の根拠にどのコマを参照したかを記述できます。また、最も難しい問いに答えることが可能になります。それは、このフィードのうち、どれがこのアカウントの本人なのかという問いです。フィードには友達、パートナー、クライアントなどが写っているので、間違った顔に基づく判定は、正しい顔の判定と同じ事故、同じほど自信たっぷりの書き言になります。しかし、すべての画像を並べてみれば、それをただ見るだけで解決できます。繰り返し現れる顔を見つけ、avatar というタイル（自分本人であると確認できる唯一の画像）と突合し、その結果を owner_face_confidence として報告します。この値が低い場合は、その人を実際より過小評価するのではなく、視覚的な読み取りの全部の確信度を弱めます。

プロフィールページのスクリーンショットを見せるのもほぼ同じことですが、そのページを表示するにはログイン済みのブラウザが必要です。一方、これらのサムネイルはすでに取得済みで、データ料金を支払っています。

信頼度の読み方

どの属性にも、1つではなく2つの数値が付いています。match（一致度） は証拠とどれだけ一致しているか、certainty（信頼度） はその証拠をどこまで信頼できるかを示します。単一の「85%」だけを報告するモデルは、これらを暗黙に掛け算して、どちらが弱いのかを捨てています。

確信度の上限は、属性ごとソースごとに設けられるため、システムが過大表明をすることはありません。アバター1枚から読み取った髪色は0.45が上限。複数の昼間の投稿から読み取った場合は0.80。Instagram自身の「account based in」を使用した国籍特定では0.95に達します。height の上限は0.15 — 写真にはスケールの手がかりが一ないからです — さらに、height、ethnicity、build は参考情報にすぎません。報告はされますが、ランキングを動かすことはできず、必須としてマークすると、完全に拒否されます。

「Unknown」は「なし」ではありません。誰にも観測できない属性は、match ではなく coverage（もれ率/カバレッジ） を下げます。ランキングは、検証の程度が低いほど事前分布に向かって縮小します。そのため、観測された2属性で0.9を獲得しても、6属性で0.75を獲得した人に負けることがあるのです。unverified（未検証）とは、行動を起こすには根拠が少なすぎるわりに良いスコアをつけた、という意味です。

結果は公開アカウントのものです。非公開アカウントは検証不可能なため、ゲートで除外されます。18歳未満は一切返されません。年齢は、自己申告の生年やInstagramのアカウント登録日から読み取られ、推定の 下限 で判定されます。このチェックは年齢が初めて読み取れるようになった時点で、以降どの出口にもされると実行されます。監査の結果、元のゲートのみのバージョンは、どの年齢も読む前にゲートが走るため、何も保護しなかったことが判明しました。} それぞれの候補には、どのプローブで見つかり、各結論が何に基づいているのか、という完全な由来が保持されます。検索ジョブは searches/ ディレクトリに置かれ、gitignoreされているため、他人のプロフィールや写真が含まれています。

ブロックされないために

instagripi は、電話アプリが使っている非公開APIを操作しています。Instagram は自動的な行動を検出してブロックし、その被害にあうブロックされるアカウントはあなた自身です — なので。

• セッションはキャッシュされ、session.json に保存されて再利用されます。ログインを 何度も最初からやり直すことは、アカウントがフラグを立てられる最も手っ取り早い方法です。 そのファイルは保持してください。

• リクエストは間隔を空けて送信され、ランダムな INSTAGRAM_DELAY_MIN–INSTAGRAM_DELAY_MAX 秒の待機が挟まれます。Instagram が待機を求めてきたら、この値を引き上げてください。

• 警告が出たら後退する。 「しばらくお待ちください」や「操作がブロックされました」は、 再試行ではなく停止を意味します。ツールのエラーメッセージにもその旨が明記されています。

• 一括読み取りは危険です。 一度に数千人のフォロワーを取得するのは、人間がアプリを 使っている様子とはまったく結びつきません。

• 実験する場合は、使い捨てアカウントまたはセカンダリアカウントを使用しましょう。

ファイル構成

.env と session.json には認証情報と有効な認証クッキーが格納され、searches/ には他ユーザーのプロフィールと写真が格納されます。それら 3 つはすべて gitignore されています。そのままにしてください。