OneSignal MCP Server

OneSignal MCP サーバー

OneSignal API と連携するための、包括的な Model Context Protocol（MCP）サーバーです。このサーバーは、OneSignal の REST API を通じて、プッシュ通知、メール、SMS、ユーザー、デバイス、セグメント、テンプレート、分析などを管理するための完全なインターフェースを提供します。

概要

この MCP サーバーは、OneSignal REST API への包括的なアクセスを提供し、OneSignal の主要な操作をすべてカバーする 57 個のツールを備えています。

🚀 主な機能

• マルチチャネルメッセージング：プッシュ通知、メール、SMS、トランザクションメッセージを送信
• ユーザーとデバイスの管理：ユーザー、デバイス、サブスクリプションに対する CRUD 操作を完備
• 高度なセグメンテーション：複雑なフィルターを使用してユーザーセグメントを作成・管理
• テンプレートシステム：メッセージテンプレートの作成、更新、管理
• iOS Live Activities：iOS Live Activities を完全サポート
• 分析とエクスポート：成果データの表示と CSV へのエクスポート
• 複数アプリのサポート：複数の OneSignal アプリをシームレスに管理
• API キー管理：API キーの作成、更新、ローテーション、削除
• 組織レベルの操作：組織全体のアプリを管理

要件

• Python 3.7 以降
• python-dotenv パッケージ
• requests パッケージ
• mcp パッケージ
• API 認証情報を持つ OneSignal アカウント

インストール

オプション 1：GitHub からクローン

# Clone the repository
git clone https://github.com/weirdbrains/onesignal-mcp.git
cd onesignal-mcp

# Install dependencies
pip install -r requirements.txt

オプション 2：パッケージとしてインストール（近日公開）

pip install onesignal-mcp

設定

1. ルートディレクトリに OneSignal の認証情報を記載した .env ファイルを作成します。

   # Default app credentials (optional, you can also add apps via the API)
   ONESIGNAL_APP_ID=your_app_id_here
   ONESIGNAL_API_KEY=your_rest_api_key_here
   
   # Organization API key (for org-level operations)
   ONESIGNAL_ORG_API_KEY=your_organization_api_key_here
   
   # Optional: Multiple app configurations
   ONESIGNAL_AIBOOKCRAFT_APP_ID=aibookcraft_app_id
   ONESIGNAL_AIBOOKCRAFT_API_KEY=aibookcraft_api_key
   
   ONESIGNAL_WEIRDBRAINS_APP_ID=weirdbrains_app_id
   ONESIGNAL_WEIRDBRAINS_API_KEY=weirdbrains_api_key
   
   # Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
   LOG_LEVEL=INFO
   

2. OneSignal の認証情報を確認します。

   • App ID：Settings > Keys & IDs > OneSignal App ID
   • REST API Key：Settings > Keys & IDs > REST API Key
   • Organization API Key：Organization Settings > API Keys

使用方法

サーバーの起動

python onesignal_server.py

サーバーが起動し、MCP システムに登録されると、57 個すべてのツールを使用できるようになります。

ツール完全リファレンス（57 個のツール）

📱 アプリ管理（5 個のツール）

• list_apps - 設定済みの OneSignal アプリをすべて一覧表示
• add_app - OneSignal アプリの設定をローカルに新規追加
• update_local_app_config - 既存のローカルアプリ設定を更新
• remove_app - ローカルの OneSignal アプリ設定を削除
• switch_app - API リクエストで使用する現在のアプリを切り替え

📨 メッセージング（8 個のツール）

• send_push_notification - プッシュ通知を送信
• send_email - OneSignal 経由でメールを送信
• send_sms - OneSignal 経由で SMS/MMS を送信
• send_transactional_message - 即時配信メッセージを送信
• view_messages - 最近送信したメッセージを表示
• view_message_details - メッセージの詳細情報を取得
• view_message_history - メッセージの履歴／受信者を表示
• cancel_message - 予約済みメッセージをキャンセル

📱 デバイス／プレイヤー（6 個のツール）

• view_devices - アプリを購読しているデバイスを表示
• view_device_details - デバイスの詳細情報を取得
• add_player - プレイヤー／デバイスを新規追加
• edit_player - 既存のプレイヤー／デバイスを編集
• delete_player - プレイヤー／デバイスのレコードを削除
• edit_tags_with_external_user_id - 外部 ID でタグを一括編集

🎯 セグメント（3 個のツール）

• view_segments - すべてのセグメントを一覧表示
• create_segment - セグメントを新規作成
• delete_segment - セグメントを削除

📄 テンプレート（6 個のツール）

• view_templates - すべてのテンプレートを一覧表示
• view_template_details - テンプレートの詳細を取得
• create_template - テンプレートを新規作成
• update_template - 既存のテンプレートを更新
• delete_template - テンプレートを削除
• copy_template_to_app - テンプレートを別のアプリにコピー

🏢 アプリ（6 個のツール）

• view_app_details - 設定済みアプリの詳細を取得
• view_apps - 組織内のすべてのアプリを一覧表示
• create_app - 新しい OneSignal アプリを作成
• update_app - 既存のアプリを更新
• view_app_api_keys - アプリの API キーを表示
• create_app_api_key - 新しい API キーを作成

🔑 API キーの管理（3 個のツール）

• delete_app_api_key - API キーを削除
• update_app_api_key - API キーを更新
• rotate_app_api_key - API キーをローテーション

👤 ユーザー（6 個のツール）

• create_user - 新しいユーザーを作成
• view_user - ユーザーの詳細を表示
• update_user - ユーザー情報を更新
• delete_user - ユーザーを削除
• view_user_identity - ユーザーの ID 情報を取得
• view_user_identity_by_subscription - サブスクリプションから ID を取得

🏷️ エイリアス（3 個のツール）

• create_or_update_alias - ユーザーのエイリアスを作成または更新
• delete_alias - ユーザーのエイリアスを削除
• create_alias_by_subscription - サブスクリプション ID からエイリアスを作成

📬 サブスクリプション（5 個のツール）

• create_subscription - 新しいサブスクリプションを作成
• update_subscription - サブスクリプションを更新
• delete_subscription - サブスクリプションを削除
• transfer_subscription - サブスクリプションをユーザー間で移管
• unsubscribe_email - メールトークンを使用して配信登録を解除

🎯 ライブアクティビティ（3 個のツール）

• start_live_activity - iOS のライブアクティビティを開始
• update_live_activity - iOS のライブアクティビティを更新
• end_live_activity - iOS のライブアクティビティを終了

📊 分析とエクスポート（3 個のツール）

• view_outcomes - 成果／コンバージョンデータを表示
• export_players_csv - プレイヤーデータを CSV にエクスポート
• export_messages_csv - メッセージを CSV にエクスポート

使用例

マルチチャネルメッセージング

# Send a push notification
await send_push_notification(
    title="Hello World",
    message="This is a test notification",
    segments=["Subscribed Users"]
)

# Send an email
await send_email(
    subject="Welcome!",
    body="Thank you for joining us",
    email_body="<html><body><h1>Welcome!</h1></body></html>",
    include_emails=["[email protected]"]
)

# Send an SMS
await send_sms(
    message="Your verification code is 12345",
    phone_numbers=["+15551234567"]
)

# Send a transactional message
await send_transactional_message(
    channel="email",
    content={"subject": "Order Confirmation", "body": "Your order has been confirmed"},
    recipients={"include_external_user_ids": ["user123"]}
)

ユーザーとデバイスの管理

# Create a user
user = await create_user(
    name="John Doe",
    email="[email protected]",
    external_id="user123",
    tags={"plan": "premium", "joined": "2024-01-01"}
)

# Add a device
device = await add_player(
    device_type=1,  # Android
    identifier="device_token_here",
    language="en",
    tags={"app_version": "1.0.0"}
)

# Update user tags across all devices
await edit_tags_with_external_user_id(
    external_user_id="user123",
    tags={"last_active": "2024-01-15", "purchases": "5"}
)

iOS ライブアクティビティ

# Start a Live Activity
await start_live_activity(
    activity_id="delivery_123",
    push_token="live_activity_push_token",
    subscription_id="user_subscription_id",
    activity_attributes={"order_number": "12345"},
    content_state={"status": "preparing", "eta": "15 mins"}
)

# Update the Live Activity
await update_live_activity(
    activity_id="delivery_123",
    name="delivery_update",
    event="update",
    content_state={"status": "on_the_way", "eta": "5 mins"}
)

分析とエクスポート

# View conversion outcomes
outcomes = await view_outcomes(
    outcome_names=["purchase", "session_duration"],
    outcome_time_range="7d",
    outcome_platforms=["ios", "android"]
)

# Export player data
export = await export_players_csv(
    start_date="2024-01-01T00:00:00Z",
    end_date="2024-01-31T23:59:59Z",
    segment_names=["Active Users"]
)

テスト

サーバーには包括的なテストスイートが含まれています。テストを実行するには：

# Run the test script
python test_onesignal_mcp.py

# Or use unittest
python -m unittest discover tests

エラー処理

サーバーは一貫性のあるエラー処理を提供します：

• すべてのエラーは標準化された形式で返されます
• 詳細なエラーメッセージで問題を特定できます
• 一時的な障害に対する自動再試行ロジック
• 適切な認証エラーメッセージ

レート制限

OneSignal は API リクエストにレート制限を適用します：

• 標準の制限：毎秒 10 リクエスト
• 一括操作：より低い制限が適用される場合があります
• サーバーにはレート制限への対処方法に関するガイダンスが含まれています

コントリビューション

コントリビューションを歓迎します！ガイドラインについては、CONTRIBUTING.md をご覧ください。

ライセンス

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

謝辞

• 優れた通知サービスを提供する OneSignal に感謝します
• Model Context Protocol を支える MCP コミュニティに感謝します
• このプロジェクトへのすべてのコントリビューターに感謝します