Instagram Mcp

@mcpware/instagram-mcp

Instagram の Graph API とシームレスに連携し、AI アプリケーションから Instagram ビジネスアカウントをプログラムで操作できる Model Context Protocol（MCP）サーバーです。

機能

🔧 ツール（モデル制御）

• プロフィール情報の取得：Instagram ビジネスプロフィールの詳細を取得します
• メディア投稿の取得：Instagram アカウントの最近の投稿を取得します
• メディアインサイトの取得：特定の投稿のエンゲージメント指標を取得します
• メディアの公開：画像や動画を Instagram にアップロードして公開します
• アカウントページの取得：アカウントに接続されている Facebook ページを一覧表示します
• 会話の取得：Instagram の DM 会話を一覧表示します（Advanced Access が必要です）
• 会話メッセージの取得：特定の会話のメッセージを読み取ります（Advanced Access が必要です）
• DM の送信：Instagram のダイレクトメッセージに返信します（Advanced Access が必要です）

📊 リソース（アプリケーション制御）

• プロフィールデータ：フォロワー数や自己紹介など、プロフィール情報にアクセスできます
• メディアフィード：エンゲージメント指標を含む最近の投稿
• インサイトデータ：投稿やアカウントのパフォーマンスに関する詳細な分析データ

💬 プロンプト（ユーザー制御）

• エンゲージメント分析：投稿のパフォーマンスを分析するための事前作成済みプロンプト
• コンテンツ戦略：コンテンツの提案を生成するためのテンプレート
• ハッシュタグ分析：ハッシュタグのパフォーマンスを評価するプロンプト

前提条件

1. Instagram ビジネスアカウント：Facebook ページに接続されている必要があります
2. Facebook 開発者アカウント：API アクセスに必要です
3. アクセストークン：適切な権限を持つ長期間有効なアクセストークン
4. Python 3.10+：MCP サーバーの実行に必要です（MCP の依存関係で必要）

必要な Instagram API 権限

標準アクセス（すぐに利用可能）：

• instagram_basic
• instagram_content_publish
• instagram_manage_insights
• instagram_manage_comments
• pages_show_list
• pages_read_engagement
• pages_manage_metadata
• pages_read_user_content
• business_management

Advanced Access（Meta アプリレビューが必要）：

• instagram_manage_messages - ダイレクトメッセージ機能に必要です

⚠️ Instagram DM 機能：Instagram のダイレクトメッセージの読み取りと送信には、Meta による Advanced Access の承認が必要です。アプリレビューの手順については、INSTAGRAM_DM_SETUP.md をご覧ください。

🔑 Instagram API 認証情報の取得方法

📖 クイックスタート：5 分で完了するセットアップガイドについては、AUTHENTICATION_GUIDE.md をご覧ください！

このセクションでは、Instagram MCP サーバーに必要な認証情報を取得する手順を説明します。

ステップ 1：Instagram ビジネスアカウントを設定する

1. ビジネスアカウントに切り替える（まだ切り替えていない場合）：

   • Instagram アプリを開き → 設定 → アカウント → プロアカウントに切り替える
   • 「ビジネス」を選択 → カテゴリを選択 → 設定を完了する

2. Facebook ページに接続する：

   • Instagram の設定 → アカウント → リンク済みアカウント → Facebook の順に移動する
   • 既存の Facebook ページに接続するか、新しいページを作成する
   • 重要：Facebook ページは自分が所有している必要があります

ステップ 2：Facebook アプリを作成する

1. Facebook Developers にアクセスする：

   • developers.facebook.com にアクセスします
   • Facebook アカウントでログインします

2. 新しいアプリを作成する：

   • 「Create App」をクリック → 「Business」を選択 → 「Next」をクリックします
   • アプリの詳細を入力します：
     • アプリ名：内容がわかる名前を選択します（例：「My Instagram MCP Server」）
     • アプリの連絡先メールアドレス：ご自身のメールアドレス
   • 「Create App」をクリックします

3. Instagram Basic Display プロダクトを追加する：

   • アプリのダッシュボードで「Add Product」をクリックします
   • 「Instagram Basic Display」を見つけて → 「Set Up」をクリックします

4. Instagram Basic Display を設定する：

   • Instagram Basic Display → Basic Display に移動します
   • Instagram App セクションで「Create New App」をクリックします
   • 利用規約に同意し、アプリを作成します

ステップ 3：アプリの認証情報を取得する

1. アプリ ID とシークレットを取得する：
   • Facebook アプリのダッシュボードで、Settings → Basic に移動します
   • App ID と App Secret をコピーします
   • 重要：App Secret は安全に保管し、公開しないでください

ステップ 4：Instagram Business API へのアクセスを設定する

1. Instagram Graph API プロダクトを追加する：

   • アプリのダッシュボードで「Add Product」をクリックします
   • 「Instagram Graph API」を見つけて → 「Set Up」をクリックします

2. アクセス許可を設定する：

   • Instagram Graph API → Permissions に移動します
   • 次のアクセス許可をリクエストします：
     • instagram_basic
     • instagram_content_publish
     • instagram_manage_insights
     • pages_show_list
     • pages_read_engagement

ステップ 5：アクセストークンを生成する

オプション A：Facebook Graph API Explorer を使用する（テストにおすすめ）

1. Graph API Explorer にアクセスする：

   • developers.facebook.com/tools/explorer にアクセスします

2. Explorer を設定する：

   • ドロップダウンからアプリを選択します
   • 「Generate Access Token」をクリックします
   • 表示されたら、必要なアクセス許可を選択します

3. ページアクセストークンを取得する：

   • Explorer で、/me/accounts に GET リクエストを送信します
   • レスポンスから Facebook ページを見つけます
   • ページの access_token をコピーします

4. Instagram Business アカウント ID を取得する：

   • ページアクセストークンを使って、/{page-id}?fields=instagram_business_account に GET リクエストを送信します
   • レスポンスから Instagram Business アカウント ID をコピーします

オプション B：Facebook Login フローを使用する（本番環境におすすめ）

1. Facebook Login を設定する：

   • アプリのダッシュボードで、「Facebook Login」プロダクトを追加します
   • 有効な OAuth リダイレクト URI を設定します

2. OAuth フローを実装する：

   # Example OAuth URL
   oauth_url = f"https://www.facebook.com/v19.0/dialog/oauth?client_id={app_id}&redirect_uri={redirect_uri}&scope=pages_show_list,instagram_basic,instagram_content_publish,instagram_manage_insights"
   

3. コードをトークンと交換する：

   # Exchange authorization code for access token
   token_url = f"https://graph.facebook.com/v19.0/oauth/access_token?client_id={app_id}&redirect_uri={redirect_uri}&client_secret={app_secret}&code={auth_code}"
   

ステップ 6：有効期間の長いアクセストークンを取得する

有効期間の短いトークンは 1 時間で期限切れになります。有効期間の長いトークン（60 日間有効）に変換します：

curl -X GET "https://graph.facebook.com/v19.0/oauth/access_token?grant_type=fb_exchange_token&client_id={app_id}&client_secret={app_secret}&fb_exchange_token={short_lived_token}"

ステップ 7：環境変数を設定する

プロジェクトのルートに .env ファイルを作成します：

# Facebook App Credentials
FACEBOOK_APP_ID=your_app_id_here
FACEBOOK_APP_SECRET=your_app_secret_here

# Instagram Access Token (long-lived)
INSTAGRAM_ACCESS_TOKEN=your_long_lived_access_token_here

# Instagram Business Account ID
INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_business_account_id_here

# Optional: API Configuration
INSTAGRAM_API_VERSION=v19.0
RATE_LIMIT_REQUESTS_PER_HOUR=200
CACHE_ENABLED=true
LOG_LEVEL=INFO

ステップ 8：セットアップをテストする

検証スクリプトを実行して、認証情報をテストします：

python scripts/setup.py

または、手動でテストします：

import os
import requests

# Test access token
access_token = os.getenv('INSTAGRAM_ACCESS_TOKEN')
response = requests.get(f'https://graph.facebook.com/v19.0/me?access_token={access_token}')
print(response.json())

🚨 重要なセキュリティ上の注意事項

1. 認証情報をバージョン管理にコミットしないでください
2. 環境変数または安全なシークレット管理を使用してください
3. アクセストークンを定期的にローテーションしてください
4. トークンの有効期限を監視してください
5. 本番環境では HTTPS のみを使用してください
6. 期限切れトークンに対する適切なエラー処理を実装してください

🔄 トークンの更新戦略

有効期間の長いトークンは 60 日後に期限切れになります。自動更新を実装します：

# Check token validity
def check_token_validity(access_token):
    url = f"https://graph.facebook.com/v19.0/me?access_token={access_token}"
    response = requests.get(url)
    return response.status_code == 200

# Refresh token before expiration
def refresh_long_lived_token(access_token, app_id, app_secret):
    url = f"https://graph.facebook.com/v19.0/oauth/access_token"
    params = {
        'grant_type': 'fb_exchange_token',
        'client_id': app_id,
        'client_secret': app_secret,
        'fb_exchange_token': access_token
    }
    response = requests.get(url, params=params)
    return response.json().get('access_token')

📋 よくある問題のトラブルシューティング

エラー：「Invalid OAuth access token」

• トークンの有効期限が切れていないか確認してください
• トークンに必要な権限があることを確認してください
• Instagram アカウントが Facebook ページに接続されていることを確認してください

エラー：「Instagram account not found」

• Instagram ビジネスアカウント ID が正しいことを確認してください
• Instagram アカウントが Facebook ページに正しくリンクされているか確認してください
• アカウントが個人アカウントではなく、ビジネスアカウントであることを確認してください

エラー：「Insufficient permissions」

• Facebook アプリで必要な権限を確認してください
• 正しいスコープを指定してアクセストークンを再生成してください
• アプリが開発モードかライブモードか確認してください

レート制限の問題

• 指数バックオフを実装してください
• 可能であればレスポンスをキャッシュしてください
• API レスポンスのレート制限ヘッダーを監視してください

インストール

1. リポジトリをクローンする：

git clone <repository-url>
cd ig-mcp

2. 依存関係をインストールする：

pip install -r requirements.txt

3. 環境変数を設定する：

cp .env.example .env
# Edit .env with your Instagram API credentials

4. MCP サーバーを設定する：

# Edit config.json with your specific settings

設定

環境変数（.env）

INSTAGRAM_ACCESS_TOKEN=your_long_lived_access_token
FACEBOOK_APP_ID=your_facebook_app_id
FACEBOOK_APP_SECRET=your_facebook_app_secret
INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_business_account_id

MCP クライアントの設定

MCP クライアントの設定（例：Claude Desktop）に以下を追加します。

{
  "mcpServers": {
    "instagram": {
      "command": "python",
      "args": ["/path/to/ig-mcp/src/instagram_mcp_server.py"],
      "env": {
        "INSTAGRAM_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

使用例

Claude Desktop での使用

1. プロフィール情報を取得する：

Can you get my Instagram profile information?

2. 最近の投稿を分析する：

Show me my last 5 Instagram posts and their engagement metrics

3. コンテンツを公開する：

Upload this image to my Instagram account with the caption "Beautiful sunset! #photography #nature"

Python MCP クライアントでの使用

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Connect to the Instagram MCP server
server_params = StdioServerParameters(
    command="python",
    args=["src/instagram_mcp_server.py"]
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        
        # Get profile information
        result = await session.call_tool("get_profile_info", {})
        print(result)

対応する API エンドポイント

プロフィール管理

• ビジネスプロフィール情報を取得する
• プロフィールの詳細を更新する（今後の機能）

メディア管理

• 最近の投稿を取得する
• 特定のメディアの詳細を取得する
• 新しいコンテンツをアップロードして公開する
• メディアを削除する（今後の機能）

分析とインサイト

• 投稿のエンゲージメント指標（いいね、コメント、シェア）
• アカウントのインサイト（リーチ、インプレッション）
• ハッシュタグのパフォーマンス分析

アカウント管理

• 接続済みの Facebook ページを一覧表示する
• ビジネスアカウントを切り替える

レート制限とベストプラクティス

このサーバーは、Instagram の API 制限に準拠するため、インテリジェントなレート制限を実装しています。

• プロフィールリクエスト：1 時間あたり 200 回
• メディアリクエスト：1 時間あたり 200 回
• 公開：1 日あたり 25 件の投稿
• インサイト：1 時間あたり 200 回

ベストプラクティス

1. 頻繁にアクセスするデータをキャッシュする
2. 可能な場合はバッチリクエストを使用する
3. リトライ時に指数バックオフを実装する
4. レート制限ヘッダーを監視する

エラー処理

このサーバーは、よくある状況に対して包括的なエラー処理を提供します。

• 認証エラー：トークンが無効または期限切れ
• 権限エラー：必要な権限が不足
• レート制限：バックオフを伴う自動再試行
• ネットワークエラー：接続タイムアウトと再試行
• API エラー：Instagram 固有のエラーレスポンス

セキュリティに関する考慮事項

1. トークンのセキュリティ：アクセストークンを安全に保管してください
2. 環境変数：トークンをバージョン管理にコミットしないでください
3. HTTPS のみ：すべての API 呼び出しで HTTPS を使用します
4. トークンの更新：トークンの自動更新を実装してください
5. 監査ログ：すべての API 操作を記録してください

開発

プロジェクト構成

ig-mcp/
├── src/
│   ├── instagram_mcp_server.py    # Main MCP server
│   ├── instagram_client.py        # Instagram API client
│   ├── models/                    # Data models
│   ├── tools/                     # MCP tools implementation
│   ├── resources/                 # MCP resources implementation
│   └── prompts/                   # MCP prompts implementation
├── tests/                         # Unit and integration tests
├── config/                        # Configuration files
├── requirements.txt               # Python dependencies
├── .env.example                   # Environment variables template
└── README.md                      # This file

テストの実行

# Run all tests
python -m pytest tests/

# Run with coverage
python -m pytest tests/ --cov=src/

# Run specific test file
python -m pytest tests/test_instagram_client.py

コントリビューション

1. リポジトリをフォークする
2. 機能ブランチを作成する（git checkout -b feature/amazing-feature）
3. 変更をコミットする（git commit -m 'Add amazing feature'）
4. ブランチにプッシュする（git push origin feature/amazing-feature）
5. プルリクエストを作成する

トラブルシューティング

よくある問題

1. 「Invalid Access Token」

   • トークンの有効期限が切れていないことを確認してください
   • トークンの権限を確認してください
   • 長期トークンを再生成してください

2. 「Rate Limit Exceeded」

   • レート制限がリセットされるまで待ってください
   • リクエストキューイングを実装してください
   • バッチリクエストを使用してください

3. 「Permission Denied」

   • Instagram ビジネスアカウントの設定を確認してください
   • Facebook ページへの接続を確認してください
   • API の権限を確認してください

デバッグモード

次の設定でデバッグログを有効にします。

LOG_LEVEL=DEBUG

トラブルシューティング

問題	原因	対処方法
me/accounts が空の [] を返す	IG が Facebook ページに接続されていないか、ページ管理者ではありません	手順 1 を実行してください
Graph API Explorer に「No configuration available」と表示される	アプリに権限が追加されていません	手順 3 を実行してください
「Generate Access Token」が無効になっている	先に「Get User Access Token」を選択する必要があります	「Get Token」ドロップダウンをクリックしてください
アプリ名が拒否される（「IG」「Insta」などを含む）	Meta が商標登録された語句をブロックしています	一般的な名前を使用してください
トークンの有効期限が切れた	短期トークンの有効期間は 1 時間です	60 日間有効なトークンを取得するには、手順 6 を実行してください
(#10) To use Instagram Graph API...	IG アカウントがビジネスアカウントではなく、個人アカウントです	IG の設定でビジネスアカウントまたはクリエイターアカウントに切り替えてください

環境変数

変数	必須	デフォルト	説明
INSTAGRAM_ACCESS_TOKEN	はい	—	Meta の長期アクセストークン
INSTAGRAM_ACCOUNT_ID	はい	—	Instagram ビジネスアカウント ID
INSTAGRAM_API_VERSION	いいえ	v19.0	Graph API のバージョン

ツール（23）

プロフィールとアカウント

ツール	説明
get_profile_info	プロフィール情報（自己紹介、フォロワー数、メディア数）を取得します
get_account_pages	接続されている Facebook ページの一覧を取得します
get_account_insights	アカウントレベルの分析データ（リーチ、プロフィール閲覧数）を取得します
validate_access_token	トークンが有効かどうかを確認します

メディアと投稿

ツール	説明
get_media_posts	エンゲージメント指標付きで最近の投稿を取得します
get_media_insights	特定の投稿の詳細な分析データを取得します
publish_media	画像または動画を投稿します
publish_carousel	カルーセル（画像または動画を 2～10 件）を投稿します
publish_reel	リールを投稿します
get_content_publishing_limit	1 日あたりの投稿上限を確認します

コメント

ツール	説明
get_comments	投稿へのコメントを取得します
post_comment	コメントを投稿します
reply_to_comment	コメントに返信します
delete_comment	コメントを削除します
hide_comment	コメントを非表示または再表示します

ダイレクトメッセージ

ツール	説明
get_conversations	DM の会話一覧を取得します
get_conversation_messages	会話内のメッセージを読み取ります
send_dm	ダイレクトメッセージを送信します

検索とコンテンツ

ツール	説明
search_hashtag	ハッシュタグ ID を検索します
get_hashtag_media	ハッシュタグに関連する人気または最近のメディアを取得します
get_stories	現在公開中のストーリーズを取得します
get_mentions	自分がタグ付けされた投稿を取得します
business_discovery	他のビジネスアカウントを検索します

制限事項

以下は Instagram Graph API の制限であり、このツールの制限ではありません。

• ビジネスアカウントまたはクリエイターアカウントのみ — 個人アカウントはサポートされていません
• 長期トークンの有効期間は 60 日です — 有効期限が切れる前に更新してください
• 1 時間あたり 200 回の API 呼び出し のレート制限
• 1 日あたり 25 件の投稿 の上限
• DM には Advanced Access が必要です — Meta アプリの審査が必要です
• ハッシュタグ検索：7 日間に 30 個までの一意なハッシュタグ

クレジット

jlbadano/ig-mcp（Python 版）を TypeScript で書き直したものです。

@mcpware のその他のプロジェクト

プロジェクト	機能	インストール
Claude Code Organizer	Claude Code のメモリ、スキル、MCP サーバー、フックを管理するビジュアルダッシュボード	npx @mcpware/claude-code-organizer
UI Annotator	任意のウェブページにホバーラベルを表示 — AI が要素を名前で参照できます	npx @mcpware/ui-annotator
Pagecast	MCP 経由でブラウザーセッションを GIF または動画として記録します	npx @mcpware/pagecast
LogoLoom	AI によるロゴデザイン → SVG → ブランドキット一式をエクスポート	npx @mcpware/logoloom

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

サポート

• 📧 メール：[email protected]
• 🐛 イシュー：GitHub のイシュー
• 📖 ドキュメント：Wiki

謝辞

• Anthropic による Model Context Protocol
• Meta による Instagram Graph API
• MCP の迅速な開発を支える FastMCP