Instagram Analytics MCP

複数のアカウントにわたって、Instagramのリールのパフォーマンスに関する質問に平易な言葉で答えるMCPサーバーです。

ポイントはAPIをラップすることではありません。リーチを実際に予測する数値はInstagram APIには存在しないため、サーバーがそれを計算するのです。

"How did my last 10 reels do?"
"What worked best this month?"
"Which of my accounts is working?"

このサーバーが解決する問題

InstagramのGraph APIは、再生回数、リーチ、保存数、シェア数、平均視聴時間を返します。

しかし、完了率（動画を実際に最後まで見た人の割合）は返しません。実際のアカウントで約700本のリールを測定したところ、完了率こそが、リールが埋もれるか拡散されるかを分ける要素です：

再生回数は結果です。完了率は原因であり、投稿から数時間以内に読み取れます（数日かかることはありません）。

これを計算するには avg_watch_time / duration が必要です。durationもAPIには存在しません。 そこでサーバーは各動画の media_url を ffprobe で調べて測定します。

これがこのサーバーが存在するすべての理由です。APIが代わりにやってくれない2つのステップと、APIが意見を持たない閾値の判断です。

ツール

すべてのリールには、日付、完了率、verdict ラベル、再生時間、再生回数、リーチ、保存数、シェア数、キャプションの最初の行（フック）、パーマリンクが付いて返されます。

1つのアカウントでも複数でも動作します。account はオプションで、デフォルトでは最初に設定したアカウントが使われます。

要件

• Instagramのプロフェッショナルアカウント（ビジネスまたはクリエイター）。個人アカウントはInstagram APIを一切使用できません

• Python 3.10以上

• ffprobe（brew install ffmpeg）-- これがないと再生時間が得られず、完了率も計算できません

セットアップ

git clone https://github.com/sskghub/instagram-analytics-mcp
cd instagram-analytics-mcp

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

cp .env.example .env

次にトークンを取得します。SETUP.md に完全な手順があります。最初のアカウントで約15分かかります：Metaアプリの作成、Instagramの追加、トークンの生成。

トークンが .env に入ったら、これで全てをチェックし、貼り付けるべきアカウントIDを教えてくれるので、探し回る必要はありません：

.venv/bin/python check_setup.py

[  OK  ] mcp package installed
[  OK  ] ffprobe found
[  OK  ] main: token works, account @yourhandle

次に、実際のデータを取得できること、MCPレイヤーがエンドツーエンドで機能することを確認します：

.venv/bin/python server.py --selftest
.venv/bin/python test_server.py

Claude Codeに登録します：

claude mcp add ig-analytics -- /absolute/path/.venv/bin/python /absolute/path/server.py

サーバーは自身の .env を読み込むため、認証情報がMCP設定ファイルに入ることはありません。その設定ファイルはコミットされますが、トークンはコミットされません。

別のアカウントを追加するには、.env に2行追加するだけです。編集するコードはありません -- アカウントは変数名から自動検出されます。

トークンの有効期限

Instagramのトークンは約60日間有効です。期限が切れると、下流のすべてが静かに何も返さなくなります。

refresh_tokens.py は、まだ有効なトークンを新しい60日間のトークンと交換します：

python refresh_tokens.py --if-older-than 7

毎週実行してください。設計を形作る制約：期限切れのトークンは更新できません。 Metaは失効したトークンを更新しないため、早めに更新することが唯一機能する戦略です。更新のたびに60日間がリセットされるので、早めの更新はコストゼロです。

スケジュール設定の注意点（macOSで launchd ジョブがファイルを読み取れず静かに失敗する罠を含む）は、SETUP.md にあります。

書き込み前に .env のバックアップを取り、重複キーを書き直し、失敗時にはアラートを出します。

更新しても古いトークンは無効化されないため、複数のマシンがそれぞれ独自の .env を独立して更新できます。トークン値をホスト間で同期する必要はありません。

構築時のメモ

実際に時間がかかった点を、汎用化できる部分としてここに残しています。

sys.exit() はCLIでは問題なく、サーバーでは致命的です。 最初のバージョンは既存のコマンドラインスクリプトの関数を再利用していました。その関数はトークンが拒否されたときに sys.exit() を呼び出し、トークンの有効期限が切れた日にサーバープロセス全体を殺していたでしょう。ツールは現在 ValueError を発生させます。SDKは標準の例外を、モデルが対応できる読みやすい結果に変換し、サーバーは生き残ります。

エラーは対処方法を示すべきです。 失効したトークンは、スタックトレースではなく再生成の手順を返します。モデルはそれを実際に修正できる人間に伝えることができます。

docstringがインターフェースです。 モデルがツールを呼ぶかどうかを判断する方法であり、各ツールは何を返すかだけでなく、いつ使うべきかを示します。

スケジュールされたジョブは静かに失敗することがあります。 macOSでは、更新スクリプトのlaunchdタイマーが Operation not permitted で失敗しました。TCCがバックグラウンドエージェントによる保護ディレクトリの読み取りをブロックするためです。ロード済みと表示され、静かに実行されないままだったでしょう。強制的に実行してログを読むことだけが、それを表面化させる方法です。

.env の重複キーは実際の罠です。 古い重複キーが、ローダーの解決方法によっては新しく書き込まれたトークンを覆い隠すことがあるため、ライターは最初の出現箇所だけでなくすべての出現箇所を書き直します。

APIの名前が変わりました。 現在は mcp.server.mcpserver.MCPServer です。古い mcp.server.fastmcp.FastMCP パスはmcp 2.xで他のレガシーモジュールとともに削除されました。オンラインのほとんどの例はまだ古いインポートを示しており、実行できません。

ライセンス

MIT