Instagram MCP Server

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 権限

Standard Access（すぐに利用可能）：

• 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 App Review が必要）：

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

⚠️ Instagram DM 機能：Instagram のダイレクトメッセージの読み取りと送信には、Meta による Advanced Access の承認が必要です。App Review の手順については、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

ライセンス

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

サポート

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

謝辞

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