instagram-mcp

リモートMCPサーバー。各チームメンバーがClaudeの会話から直接Instagramのカルーセルや単一画像を自分自身のInstagramプロフェッショナルアカウントに公開できるようにします。他の誰のアカウントにも公開できません。

ベアラートークンが個人を識別します。個人はデータベース内の1つのInstagramアカウントに正確にマッピングされます。どのツールもInstagramアカウントIDをパラメータとして受け取らないため、誤ったIDを渡してチームメイトのアカウントに投稿することは構造的に不可能です。

Metaアプリは開発モードで動作し、すべてのチームメンバーがInstagramテスターとして追加されています。Metaアプリレビュー、OAuthログインフロー、公開は一切不要です。これは意図的な設計です。

Claudeに接続する（このセクションをそのままチームメイトに送信してください）

管理者からサーバーURLと個人アクセストークン（igmcp_で始まります）の2つが必要です。トークンはパスワードのように扱ってください。保持している人は誰でもあなたのInstagramアカウントに投稿できます。

1. Claudeで設定 → コネクタ → カスタムコネクタを追加を開きます。

2. このURLを貼り付けます：

   https://YOUR-DEPLOYMENT.vercel.app/api/mcp

   （管理者が実際のホスト名を提供します）

3. コネクタが認証を求める場所で、次のヘッダーを追加します。左側に名前、右側に値：

   Authorization: Bearer igmcp_your_token_here

   ヘッダー名：Authorization。ヘッダー値：単語Bearer、1つのスペース、次にあなたのトークン。それ以外は何も入れません。

4. 保存します。これで、任意の会話で「これらの5枚のスライドをこのキャプションでカルーセルとして公開して」などと言うと、Claudeが画像をアップロードしてあなたのアカウントに投稿します。

Claudeに依頼できること：

• カルーセルを公開する（2～10枚の画像、投稿全体で1つのキャプション）

• 単一画像を公開する

• 今日の残り投稿数を確認する（InstagramはAPI公開を24時間あたり100件に制限しています）

• トークンの健全性を確認する（Instagram接続は期限切れのかなり前に自動更新されます。これで問題がないか確認できます）

• 最近の投稿を一覧表示する（常に自分の投稿のみ）

公開が途中で失敗した場合は、Claudeに同じ公開を再試行するよう依頼するだけです。サーバーは中断したところから再開し、二重投稿は発生しません。

新しいチームメンバーのオンボーディング（管理者向け）

前提条件（1人につき1回）：

1. そのInstagramアカウントはプロフェッショナルアカウント（ビジネスまたはクリエイター）である必要があります。

2. developers.facebook.comでMetaアプリを開き、Instagram → Instagramログインを使用したAPIセットアップに進み、アカウントをInstagramテスターとして追加します。招待を承諾する必要があります（Instagramアプリ → 設定 → ウェブサイトの権限 → アプリとウェブサイト → テスター招待）。

3. アプリダッシュボードからアカウントの長期アクセストークンを生成します（テスターアカウントの横にある「トークンを生成」ボタン）。トークンをコピーし、アカウントのユーザーIDをメモします。

次に、シードを実行します（自分のマシンから、このリポジトリ内で、.env.localが入力された状態で）：

npm run add-member -- --name "Ada" --ig-user-id 17840000000000000 --ig-username ada.builds
# pastes the long-lived IG token when prompted (kept out of shell history)

スクリプトはgraph.instagram.comに対してトークンをライブで検証し、渡されたIDとは異なるアカウントのトークンである場合はシードを拒否し、メンバーのigmcp_ベアラートークンを1回だけ出力します。上記の「Claudeに接続する」セクションとともに、安全なチャネルを介してメンバーに送信します。

メンバーを無効化するには：team_membersの該当行でrevoked_at = now()を設定します。そのトークンは即座に401を返すようになります。

アーキテクチャ

instagram-mcp/
├── api/
│   ├── mcp.ts                 # MCP endpoint (Streamable HTTP), bearer auth wrapper
│   └── cron/refresh-tokens.ts # Vercel Cron target (daily; refreshes tokens nearing expiry)
├── src/
│   ├── auth.ts                # bearer lookup → resolves the calling member
│   ├── crypto.ts              # AES-256-GCM for IG tokens, SHA-256 for bearer hashes
│   ├── instagram.ts           # containers, polling, publish, refresh, idempotent resume
│   ├── storage.ts             # R2 uploads (per-member key prefix)
│   ├── db.ts                  # Supabase (service role)
│   ├── refresh.ts             # refresh loop shared by cron + CLI
│   └── tools/                 # one file per tool
├── scripts/
│   ├── add-member.ts          # seeds a member, generates their bearer token
│   └── refresh-tokens.ts      # manual run of the refresh loop
├── supabase/migrations/       # schema (already applied via the Supabase connector)
├── .env.example               # every key, documented
└── README.md

主要な設計判断：

• トランスポート：mcp-handler v2（VercelのMCPアダプター）と@modelcontextprotocol/server v2 — Streamable HTTPのみ。非推奨のHTTP+SSEトランスポートはv2で上流から削除されており、これはまさに望ましい状態です。手作りのトランスポートはありません。

• ホスト：すべてがhttps://graph.instagram.com（Instagramログインパス）と通信します。graph.facebook.comはFacebookログインパスに属し、誤解を招くトークン解析エラーで失敗します。ほとんどのチュートリアルがこれを間違えています。

• 認証：すべてのリクエストにAuthorization: Bearer <token>。トークンはハッシュ化（SHA-256）され、検索され、定数時間比較で再チェックされます。不明なトークンと無効化されたトークンは、処理前に401を返します。InstagramトークンはPostgres内でAES-256-GCM暗号化されて保存されます。ベアラートークンが生の状態で保存されることはありません。

• 冪等性：冪等性キー（メンバー + 画像URL + キャプション）は、Meta呼び出しの前にpostsに書き込まれます。子コンテナIDは作成時に永続化されます。再試行ではFINISHEDの子を再利用し、EXPIRED/ERRORの子のみを再作成します。同じ親コンテナIDの再公開は安全です（media_publishはコンテナごとに冪等です）。そのため、半分公開されたカルーセルが重複することは決してありません。

• トークン更新：Vercel Cronが毎日実行されます。トークンは60日間有効で、それぞれが25日の更新期間に入ると更新されます。そのため、失敗した実行は月に1回ではなく、24時間ごとに新たに再試行されます。1人のメンバーの失敗がループ全体を停止させることはありません。永続的な失敗（アクセス権限の失効、アカウントタイプの変更）は行にマークされ、無限に再試行する代わりにcheck_token_healthを通じて表面化します。

デプロイ（管理者向け）

npm install
npm run typecheck && npm test     # 19 unit tests, live tests skip without creds

vercel login
vercel link                        # or create the project
# Set every var from .env.example in Vercel → Project → Settings → Environment Variables
vercel --prod

次に、デプロイURLを上記の「Claudeに接続する」セクションに配置します。

Supabaseは、このサーバーのみをホストする専用プロジェクトである必要があります。別のアプリと共有するプロジェクトではありません。team_membersとpostsは汎用的な名前であり、サービスロールクライアントはテーブルへの完全なアクセス権を持つため、無関係な製品とスキーマを共有することは、衝突（および爆発半径）のリスクがあります。自分のアカウントでプロジェクトを作成し、supabase/migrations/のマイグレーションをSQLエディタまたはSupabase MCPコネクタを介して適用します。

R2バケットは、R2_PUBLIC_BASE_URLに一致するパブリックアクセス（カスタムドメインまたはr2.dev）を有効にする必要があります。

ライブ受け入れテスト

.env.localが入力され、少なくとも1人のメンバーがシードされている状態で：

LIVE_MEMBER_BEARER_TOKEN=igmcp_...            npm test   # upload + token health, no posting
LIVE_MEMBER_BEARER_TOKEN=igmcp_... LIVE_PUBLISH=1 npm test   # ⚠ creates REAL posts
# add LIVE_MEMBER_BEARER_TOKEN_2=igmcp_... for the two-members-two-accounts test

運用上の注意

• 静かな障害モード #1 は期限切れトークン — 投稿が停止し、誰も気づきません。Cronは失敗を大々的にマークし（200以外 → Vercelダッシュボードで赤い実行）、check_token_healthはメンバーごとの有効期限までの日数と更新失敗を報告します。

• Instagramは公開をアカウントごとに24時間のローリングウィンドウで100件に制限しています。get_publishing_limitはライブカウンターを読み取ります。

• コンテナは約24時間で期限切れになり、アカウントごとに約50件の保留中コンテナの上限があります。これが、再試行パスが新しいコンテナを作成する代わりに既存のコンテナを再利用するもう一つの理由です。

• カルーセルスライドは同じアスペクト比にしてください。Instagramは最初のスライドに合わせてすべてをトリミングします。JPEG/PNGのみ、8MB以下。