Instagram MCP Server

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

機能

🔧 ツール（モデル制御）

• Get Profile Info: Instagram のビジネスプロフィール情報を取得します。

• Get Media Posts: Instagram アカウントの最近の投稿を取得します。

• Get Media Insights: 特定の投稿のエンゲージメント指標を取得します。

• Publish Media: 画像や動画を Instagram にアップロードして公開します。

• Get Account Pages: アカウントに接続された Facebook ページの一覧を取得します。

• Get Conversations: Instagram の DM 会話を一覧表示します（Advanced Access が必要）。

• Get Conversation Messages: 特定の会話からメッセージを読み取ります（Advanced Access が必要）。

• Send DM: Instagram のダイレクトメッセージに返信します（Advanced Access が必要）。

📊 リソース（アプリ制御）

• Profile Data: フォロワー数やプロフィールなどの情報へのアクセス。

• Media Feed: エンゲージメント指標を含む最近の投稿。

• Insights Data: 投稿とアカウントパフォーマンスの詳細な分析。

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

• Analyze Engagement: 投稿パフォーマンス分析用の事前構築済みプロンプト。

• Content Strategy: コンテンツのレコメンデーションを生成するためのテンプレート。

• Hashtag Analysis: ハッシュタグのパフォーマンス評価用のプロンプト。

Related MCP server: instagram-mcp

前提条件

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 のアプリ審査が必要）:

• 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. 新しいアプリを作成する:

   • 「アプリを作成」をクリック → 「ビジネス」を選択 → 「次へ」をクリック

   • アプリの詳細を入力:

     • アプリ名: 分かりやすい名前を選択（例: "My Instagram MCP Server"）

     • アプリ連絡先メール: 自分のメールアドレス

   • 「アプリを作成」をクリック

3. Instagram Basic Display プロダクトの追加:

   • アプリのダッシュボードで「プロダクトを追加」をクリック

   • 「Instagram Basic Display」を見つけて → 「セットアップ」をクリック

4. Instagram Basic Display の設定:

   • Instagram Basic Display → Basic Display に移動

   • Instagram アプリセクションの「新しいアプリを作成」をクリック

   • 利用規約に同意してアプリを作成

ステップ 3: アプリの認証情報を取得

1. アプリ ID とシークレットを取得:

   • アプリのダッシュボードで設定 → 基本に移動

   • アプリ ID と アプリシークレット をコピー

   • 重要: アプリシークレットは安全に保管し、公開しないこと

ステップ 4: Instagram ビジネス API アクセスの設定

1. Instagram Graph API プロダクトの追加:

   • アプリのダッシュボードで「プロダクトを追加」をクリック

   • 「Instagram Graph API」を見つけて → 「セットアップ」をクリック

2. 権限の設定:

   • Instagram Graph API → 権限 に移動

   • 次の権限をリクエストする:

     • 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 の設定:

   • ドロップダウンからアプリを選択

   • 「アクセストークンの生成」をクリック

   • プロンプトが表示されたら必要な権限を選択

3. ページアクセストークンの取得:

   • エクスプローラーで /me/accounts に GET リクエストを送信

   • レスポンス内の自分の Facebook ページを見つける

   • ページの access_token をコピー

4. Instagram ビジネスアカウント ID の取得:

   • ページアクセストークンを使って、/{page-id}?fields=instagram_business_account に GET リクエストを送信

   • レスポンスから Instagram ビジネスアカウント ID をコピー

オプション B: Facebook ログインフローを使用（本番推奨）

1. Facebook Login の設定:

   • アプリのダッシュボードで「Facebook ログイン」プロダクトを追加

   • 有効な 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 アプリで必要な権限を再確認する

• 正しいスコープでアクセストークンを再生成する

• アプリが開発モードか公開モード（Live）かを確認する

レート制限の問題

• 指数バックオフを実装する

• 可能な場合はレスポンスをキャッシュする

• 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 ファイルをご覧ください。

サポート

• 📧 メール: support@example.com

• 🐛 問題報告: GitHub Issues

• 📖 ドキュメント: Wiki

謝辞

• Model Context Protocol（Anthropic 提供）

• Instagram Graph API（Meta 提供）

• FastMCP（MCP 開発を迅速化）