instagram-mcp

instagram-mcp

Instagram クリエイター向けの MCP サーバーです。Meta の公式 Instagram API のみを使用し、AI エージェントで投稿、スケジュール設定、コメントや DM のトリアージ、インサイトの確認ができます。セルフホスト可能で、書き込み操作にはすべて承認が必要です。

ステータス：1.0.0。docs/CONTRACT.md に動作仕様を記載しており、コードを参照しない独立したテストスイートで検証しています。テストアカウントを使い、実際の Meta に対してエンドツーエンドで動作確認済みです（Facebook Login 経由、2026-11-01）：投稿、スケジュール設定、コメント、DM、インサイト、Webhook、クリーンアップ。新しいアプリのデフォルトである Unified Login も、アプリを Standard Access で Live にした状態で、2026-11-01 にエンドツーエンドで動作確認済みです：セットアップ、トークン、読み取り、投稿（URL およびローカルファイル）、スケジュール設定、削除、コメントの書き込み、会話、Instagram Tester への DM 送信、メッセージングプロフィール。未確認の項目：Unified Login 経由での実際の Webhook イベント（Meta のテストイベントは届きますが、実際のコメントや DM は届きませんでした。おそらく App Review が必要です）、Instagram Login 経由の動作、コラボレーション招待とブランドコンテンツ、別アカウントのコメントや @メンションを必要とする操作（非表示、プライベート返信、メンションへの返信）。十分に文書化されていない Meta の動作はdocs/TESTING-LIVE.mdに記載しており、サーバーはどちらの結果にも対応します。

インストール

git clone https://github.com/pratikgh0se/instagram-mcp.git && cd instagram-mcp && npm ci && npm run build

続いてクイックスタートに進むか、まだ Meta アプリをお持ちでない場合はdocs/SETUP.mdを参照してください。

概要

• セルフホスト可能です。お使いのマシン（またはご自身のサーバー）で動作します。第三者を経由してデータが転送されることはありません。トークンはキーリングまたは暗号化ファイルに保存されます。
• Meta の公式 API のみを使用します。スクレイピング、非公開 API、パスワードログイン、ブラウザー自動化は行いません。
• デフォルトでセキュリティを重視しています。ローカルトランスポート、Bearer 認証で保護された HTTP、機密情報を伏せたログ、アカウント許可リスト、すべての書き込み操作前の承認に対応しています。セキュリティモデルを参照してください。
• クリエイターのワークフロー向けに構築されています。投稿とスケジュール設定、コメントのトリアージ、DM、インサイト、レポート、メディアキット、競合アカウントのベンチマークを扱う 42 個のツールを備えています。

機能

領域	ツール数	内容
アカウント、認証、運用	6	設定済みアカウントと解決済みの機能、プロフィール、投稿クォータとレート使用状況、操作台帳と監査ログ、instagram_approve
メディアとアーカイブ	5	自分の投稿とストーリーズの一覧表示と読み取り、メタデータのサイドカーファイル付きメディアのダウンロード、アカウントの差分バックアップ
投稿	6	画像、リール、ストーリーズ、カルーセルの事前確認と投稿（ローカルファイルまたは URL）、スケジュール設定、スケジュール一覧とキャンセル、メディアの削除、コメントのオン／オフ、投稿ステータス
コメント、メンション、受信箱	7	コメント一覧、統合トリアージ受信箱（未返信、対応済み）、一括返信、非表示、再表示、削除、プライベート返信、メンションとタグ付けされたメディア、メンションへの返信
ダイレクトメッセージ	4	24 時間ウィンドウの状態を含む会話、メッセージの読み取り、送信（テキスト、メディア、リアクション、クイック返信）、アイスブレーカーと固定メニュー
インサイトとレポート	8	アカウントとメディアのインサイト、オーディエンスの属性、保存済みの日次スナップショットと成長状況、パフォーマンスレポート、投稿に最適な時間、メディアキット
発見とパートナーシップ	6	ビジネス検索、最大 10 アカウントとのベンチマーク、ハッシュタグ検索とメディア、コラボレーション招待（Facebook Login 経由）

ツールごとの詳しいリファレンス：docs/TOOLS.md（実行中のレジストリから生成）。

できないこと（その理由）

公式 API ではこれらを提供していないため、このサーバーでも利用できません。

• アカウントをフォローまたはフォロー解除する。
• フォロワーや、自分がフォローしているアカウントの一覧を取得する。
• 投稿やコメントに「いいね」したり、投稿を保存したりする。
• アプリで投稿をアーカイブする（プロフィールから非表示にする）。
• 投稿やコメントをピン留めする。
• 公開後にキャプションを編集する。
• 他の人の非公開コンテンツを閲覧する、または自分が所有するビジネスアカウントやクリエイターアカウント以外のアカウントからメディアをダウンロードする。
• パートナーシップ広告を配信する（これは Marketing API です）。
• Creator Marketplace を使用する（ブランド側の機能であり、App Review が必要です）。

既知の制限事項

• Development モードでのダイレクトメッセージ（facebook ログイン経路）：他の参加者にアプリ上のロール（Instagram Tester ロール。詳しくは docs/SETUP.md のセクション F を参照）が割り当てられるまで、instagram_list_conversations は空のリストを返します。2026-11-01 に確認済み。docs/CONTRACT.md U29 を参照してください。
• DM の送信：Development モードでは、Instagram Tester への送信は、24 時間以内であっても MESSAGING_WINDOW_CLOSED（Meta (#10)、サブコード 2534022）で失敗しました。アプリを Live にすると（Standard Access のまま）、同じ送信が成功しました（2026-11-01、facebook 経路で確認済み）。アプリ上にロールがない相手への送信には、Meta によると instagram_manage_messages の Advanced Access が必要です（App Review が必要。未テスト）。コメントへの非公開返信は機能します。
• facebook 経路では、実際の Webhook（コメントと DM）が届くのは、アプリが Live になり、Page に登録された後に限られます（webhooks subscribe-page、デフォルトのフィールドは feed、pages_manage_metadata が必要。DM に追加の権限は不要）。Live にするには、公開されているプライバシーポリシーのページとデータ削除ページが必要です。テンプレートと無料ホスティングの手順は docs/legal/ と docs/SETUP.md のセクション O にあります。
• Unified Login：セットアップ、トークン、読み取り、公開、予約投稿、削除、コメントの書き込み、会話、Instagram Tester への DM、メッセージングプロフィールについて、2026-11-01 に実環境でテスト済みです（アプリは Live、Standard Access）。他の人のコメントの非表示、非公開返信、@メンションへの返信は2026-11-02に確認済みです。実際の Webhook イベントは Unified アプリに配信されませんでした（テストイベントのみ。Webhooks を参照）。ハッシュタグ検索には App Review が必要です（Meta コード 10）。
• Instagram Login：Meta はアプリ向けのダッシュボード Instagram ログイントークンの提供を終了しました（2026-11-01 に確認済み）。すでにそのトークンを持っているアプリでは引き続きこの経路を利用できますが、メンテナーによる実環境テストは行われていません。
• instagram_get_profile は、facebook および unified ログイン経路で account_type: null を返します（Graph API ではその値を取得できません）。その旨を示す警告が表示されます。
• メンションへの返信が機能するのは、キャプションまたはコメント内の @メンションのみであり、写真のタグには対応していません。

どのログイン方法を選ぶか

各アカウントには、3 種類のログイン方法のいずれかが設定されています。どれも公式エンドポイントのみを使用します。Facebook ページを持たない新しいアプリには Unified Login を使用してください。Meta はアプリ向けの Instagram Login を提供しなくなりました。

機能	Unified Login（新しいアプリ）	Facebook Login（ビジネス向け）	Instagram Login（レガシー）
Facebook ページが必要	いいえ（ビジネスポートフォリオが必要）	はい	いいえ
URL から公開（画像、リール、ストーリーズ、カルーセル）	はい（2026-11-01 確認済み）	はい	はい
ローカルファイルを公開	再開可能なアップロードで動画を公開（トンネル不要）、画像はメディアホスト経由	再開可能なアップロードで動画を公開（トンネル不要）、画像は引き続きメディアホスト経由	メディアホスト経由で画像と動画を公開（トンネルが必要）
コメント、メンション、インサイト、スケジュール設定	インサイト、スケジュール設定、自分のコメントへの書き込み（コメント、返信、自分のコメントの非表示／再表示、削除、コメントのオフ／オン）：確認済み。他者のコメントの非表示や非公開返信、メンション：未テスト	はい	はい
ダイレクトメッセージ	読み取りと送信（アプリが Live の場合、24 時間以内に Instagram テスターへ送信）：2026-11-01 確認済み。アイスブレーカーの設定／解除も確認済み	読み取り：はい（Development モードのロールユーザー）。送信：Advanced Access が必要	検証済み（未確認）
メディアを削除	はい（2026-11-01 確認済み）	はい	検証済み（未確認）
ビジネスディスカバリー（競合アカウントの検索、ベンチマーク）	はい（読み取り確認済み）	はい	いいえ
ハッシュタグ検索	試験済み。App Review が必要（code 10）	はい	いいえ
ブランドコンテンツと有料パートナーシップのフラグ	試験済み（テストには実際のスポンサーが必要）	はい	試験済み（未確認）
コラボレーションの招待	試験済み（返信できる招待がない）	はい	試験済み（未確認）
story_insights webhook	未確認（Unified では実際の webhook イベントが届かなかった）	はい	いいえ
トークン	有効期限のないシステムユーザートークン	長期有効なページトークン	60 日間有効。サーバーで更新可能

「試験済み」とは、サーバーが呼び出しを試み、Meta に拒否された場合、そのアカウントについて拒否されたことを記憶し、もう一方のログイン方法を示す CAPABILITY_UNAVAILABLE を返すことを意味します。推奨事項：Facebook ページを持たない新しいアプリには Unified Login（ビジネスポートフォリオが必要）、エンドツーエンドで検証済みの方法には Facebook Login を使用してください。docs/SETUP.md のセクション B で選択方法を確認できます。

クイックスタート

Node.js 22.13 以降が必要です。インストールはソースから行います（パッケージはまだ npm に公開されていません）。

git clone https://github.com/pratikgh0se/instagram-mcp.git
cd instagram-mcp
npm ci
npm run build

# Optional: put the CLI on your PATH. Otherwise use `node dist/cli.js` wherever this README says `instagram-mcp`.
npm link

instagram-mcp accounts add --alias main --login unified        # facebook path: --login facebook --page-id <PAGE_ID> --app-id <APP_ID>
instagram-mcp auth set-token --account main                    # hidden prompt, or pipe it on stdin; ig_user_id is found automatically
# facebook path only: instagram-mcp auth set-app-secret         (hidden prompt; the token exchange needs it)
# optional on unified: instagram-mcp auth set-app-secret --account main   (per-account secret, useful with accounts from more than one Meta app)
instagram-mcp doctor

Unified の方法では、ダッシュボードの「API setup with Unified login」から取得したトークンが必要です（docs/SETUP.md のセクション H2 を参照）。アプリ ID とページ ID は必要ありません。facebook の方法では、ページ ID、アプリ ID、アプリシークレットの 3 つが必要です。Graph API Explorer のトークンは約 1 時間で期限切れになるため、生成したらすぐに auth set-token を実行してください。アプリシークレットがないと長期有効化の交換に失敗し、トークンは 1 時間以内に期限切れになります。

これを使うには、プロフェッショナル Instagram アカウント、Meta アプリ、トークンが必要です。docs/SETUP.md では、Meta 開発者アカウントを持っていない状態から、手順を追って説明しています。doctor は各チェックの結果を PASS、WARN、FAIL のいずれかで表示し、それぞれの修正方法も示します。機能が誤って CAPABILITY_UNAVAILABLE（キャッシュされた「利用不可」）を報告した場合は、instagram-mcp capabilities reset --account <alias> でリセットしてください。

MCP クライアントを接続する

絶対パスを使用してください。/ABSOLUTE/PATH/TO/instagram-mcp をクローン先に置き換えてください。Claude Desktop の場合は、command -v node で取得した絶対パスの node も使用してください（Desktop はシェルの PATH を参照しないため、nvm でインストールした node は node とだけ指定しても見つかりません）。

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "instagram": {
      "command": "/ABSOLUTE/PATH/TO/node",
      "args": ["/ABSOLUTE/PATH/TO/instagram-mcp/dist/cli.js", "serve"]
    }
  }
}

Claude Code（stdio）：

claude mcp add instagram -- node /ABSOLUTE/PATH/TO/instagram-mcp/dist/cli.js serve

HTTP モード（/mcp での Streamable HTTP、Bearer 認証が必要、デフォルトではループバック）：

instagram-mcp http-token rotate        # prints a new bearer once; stores it in your secrets backend
instagram-mcp serve --http --port 8765

claude mcp add --transport http instagram http://127.0.0.1:8765/mcp --header "Authorization: Bearer <TOKEN>"

保存済みの Bearer がない場合、サーバーは HTTP モードでの起動を拒否します。また、http.allow_remote が true でない場合、ループバック以外へのバインドを拒否します。INSTAGRAM_MCP_HTTP_HOST は http.host を上書きします（--host フラグは両方より優先されます）。allow_remote のルールは実際に適用されるホストに適用されます。

ヒント：クライアントでは instagram_approve の実行前に確認を求めるよう設定し、ほかの処理はすべて実行できるようにしてください。Instagram に変更を加えるツールはこれだけです。

長時間かかる承認：大規模なカルーセル（最大 20 件）の公開では、Instagram が各コンテナを処理する間、数分かかることがあります。クライアントから進行状況トークンが渡されると、instagram_approve は MCP の進行状況通知を送信します。そのため、クライアントにリクエストのタイムアウト（多くのクライアントではデフォルトで 60 秒）がある場合は、進行状況に応じたタイムアウトのリセット（MCP SDK の resetTimeoutOnProgress）を有効にするか、このツールのタイムアウトを延長してください。承認の途中でクライアントがサーバーを終了した場合、次回のサーバー起動時またはいずれかの操作の照会時に、その操作は unknown として記録されます。照合には instagram_get_operation を使用してください。シャットダウン時（stdin のクローズ、SIGTERM、SIGINT）、サーバーは進行中の承認が完了するまで最大 INSTAGRAM_MCP_DRAIN_MS（デフォルトは 5 分）待機します。2 回目のシグナルを受信すると、直ちに終了します。

書き込みの仕組み

Instagram 側への書き込みはすべて、次の 2 つの手順を経由します。

1. instagram_preflight_<action> は読み取り専用です。入力、ポリシー、機能、クォータ、メディア仕様を検証し、現在の対象の状態を読み取って、プレビュー、警告、有効期限付きの approval_id（デフォルトは 10 分）を返します。
2. instagram_approve に confirm: true を指定すると、プレビューされた内容をそのまま実行します。承認は 1 回限りで、対象がまだ存在することを再確認し、監査行を記録します。繰り返し実行すると、再実行せずに保存済みの結果を返します。

config.json の policy にある制御項目：

• read_only: true にすると、すべての preflight と approve が POLICY_DENIED で失敗します。
• dry_run: true にすると、instagram_approve は検証を行い、計画された Graph 呼び出しを返しますが、何も送信しません。最初の試行に適しています。
• disabled_actions: ["delete_media", "send_message"] は、指定したアクションをブロックします。
• approval_ttl_seconds は承認の有効期間を設定します。
• verify_remote_media（デフォルトは false）：true の場合、preflight はリモートメディアのホストを解決し（DNS を固定）、それぞれに HEAD リクエストを 1 回送信します。false の場合、Meta 以外へのリクエストは行われず、MEDIA_UNVERIFIED 警告が返されます。
• confirm_via_elicitation（デフォルトは true）：クライアントがサポートしている場合、instagram_approve は MCP の elicitation を通じて確認を求めます。拒否すると POLICY_DENIED が返されます。

その他のキー：local_media_dirs（配列、デフォルトは ["<home>/media"]）は、ローカルの公開メディアを取得できる唯一のディレクトリを列挙します。media_host.bind（デフォルトは 127.0.0.1）と media_host.allow_remote（デフォルトは false。Docker などでループバック以外にバインドする場合は必須）。

公開処理で二重投稿が発生することはありません。media_publish が曖昧な失敗になった場合は、作成 ID とともに結果が unknown として記録され、再試行するのではなく instagram_get_operation で照合します。

スケジュール設定とデーモン

instagram_preflight_publish に publish_at を指定すると、承認時にスケジュール済みジョブが作成されます。ジョブはデーモン（または cron から instagram-mcp scheduler run-once）によって実行されます。指定時刻の直前にコンテナが作成され、指定時刻に公開されます。missed_grace_minutes（デフォルトは 60 分）を超えて実行されなかったジョブは missed とマークされ、遅れて投稿されることはありません。

instagram-mcp daemon            # scheduler, webhooks (if enabled), daily snapshots, token refresh
instagram-mcp daemon --http     # also serves the MCP endpoint over HTTP

状態ディレクトリごとにデーモンを 1 つ実行します。すぐに使える launchd および systemd ファイルと Dockerfile が含まれています。docs/SETUP.md のセクション N を参照してください。

Webhook

デーモンは POST /webhooks/instagram で Instagram の webhook（コメント、メンション、メッセージなど）を受信し、アプリシークレットを使って X-Hub-Signature-256 を検証できます。安定した公開 HTTPS URL が必要です（名前付き Cloudflare Tunnel が利用できます。examples/cloudflared-config.yml を参照）。Webhook がない場合、受信トレイは代わりに API をポーリングします。Unified Login の場合は、ダッシュボードの「3. Configure webhooks」と、アカウントごとの Webhook Subscription トグルを使用してください（Page subscription は不要です）。2026-11-01 時点で確認済み：ダッシュボードの Test event は署名付きで Unified アカウントに帰属する形でデーモンに届きますが、実際のコメントと DM は Unified アプリに配信されませんでした（おそらく App Review / Advanced Access が必要ですが、未確認です）。そのため、この場合は受信トレイがポーリングに依存します。Facebook Login の場合は、Meta が実際のイベントを配信できるように instagram-mcp webhooks subscribe-page --account <alias> を一度実行してください（webhooks page-subscription で状態を確認できます）。セットアップについては、docs/SETUP.md のセクション O と P を参照してください。

セキュリティモデル

• シークレットは macOS キーチェーン、AES-256-GCM で暗号化されたファイル、または読み取り専用の環境変数に保存されます。ツールの出力、エラー、ログ、監査行、SQLite データベースに表示されることはありません。
• 状態ディレクトリのモードは 0700、ファイルのモードは 0600 です。グループまたはその他のユーザーが書き込み可能な設定ファイル、所有者が異なる設定ファイル、シンボリックリンクは拒否されます。テストモード以外では、暗号化されていない（http）API URL の上書きとメディアホスト URL は拒否されます。
• キーチェーンの項目は、ユーザーとして実行されているすべてのプロセスから読み取ることができます。それが問題となる場合は、パスフレーズを使用する暗号化ファイルバックエンドを使用してください（docs/SECURITY-MODEL.md を参照）。
• HTTP トランスポート：デフォルトではループバック、必須のベアラートークン（定時間比較）、Host と Origin のチェック、1 MB のボディ制限、失敗時のレート制限、セッションのアイドルタイムアウト、サーバーのタイムアウト。
• Webhook は有効な HMAC 署名がある場合にのみ受け付けられます。メディアホストが配信するのは、ステージングされたファイル用の推測不能で有効期限のあるトークンのみです。
• ユーザー提供の URL は SSRF ガードを使い、HTTPS 経由でのみ取得されます。ダウンロード元は Meta CDN ホストに限定されます。
• どのツールからも、設定済みのアカウントにのみアクセスできます。

詳細と脅威モデルについては、docs/SECURITY-MODEL.md を参照してください。報告先：SECURITY.md。

ドキュメント

ドキュメント	内容
docs/SETUP.md	新しい Meta 開発者アカウントからの手順：アプリ、トークン、インストール、トンネル、デーモン、Go Live、Webhook
docs/legal/	Go Live に必要なプライバシーポリシーとデータ削除のテンプレート
docs/TOOLS.md	生成されたツールリファレンス
docs/CONTRACT.md	動作仕様
docs/TESTING-LIVE.md	ライブ環境でのエンドツーエンドチェックリストと未検証の上流側の情報
docs/SECURITY-MODEL.md	脅威モデル
AGENTS.md	このサーバーをインストールして運用する AI エージェント向けプレイブック
CHANGELOG.md	リリースノート
docs/superpowers/specs/2026-10-29-instagram-mcp-v1-design.md	v1 設計仕様

ライセンス

MIT。Copyright (c) 2026 Pratik Ghose。LICENSE を参照してください。