OneSignal MCP サーバー

OneSignal APIと連携するためのモデルコンテキストプロトコル（MCP）サーバー。このサーバーは、OneSignalのREST APIを介してプッシュ通知、メール、SMS、ユーザーデバイス、セグメント、テンプレートなどを管理するための便利なインターフェースを提供します。

概要

このMCPサーバーは、OneSignal REST APIをラップし、OneSignalアプリケーションの管理とユーザーへのメッセージ送信のためのツールセットを提供します。以下の主要なOneSignal操作をすべてサポートしています。

プッシュ通知、メール、SMSの送信
ユーザーのデバイスとサブスクリプションの管理
セグメントの作成と管理
テンプレートの作成と管理
アプリ情報と分析の表示
組織レベルの運用
複数のOneSignalアプリケーションの管理

要件

Python 3.7以上
python-dotenvパッケージ
requestsパッケージ
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

構成

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
OneSignal の認証情報は、OneSignal ダッシュボードで確認できます。
- アプリID: 設定 > キーとID > OneSignal アプリID
- REST APIキー: 設定 > キーとID > REST APIキー
- 組織APIキー: 組織設定 > APIキー

使用法

サーバーの実行

python onesignal_server.py

サーバーが起動し、MCP システムに自身を登録して、ツールを使用できるようになります。

基本的な使用例

プッシュ通知の送信

# Send a notification to all subscribed users
result = await send_notification(
    title="Hello World",
    message="This is a test notification",
    segment="Subscribed Users"
)
print(result)

複数のアプリを操作する

# Add a new app configuration
await add_app(
    key="my_second_app", 
    app_id="second-app-id", 
    api_key="second-app-api-key", 
    name="My Second App"
)

# List all configured apps
apps = await list_apps()
print(apps)

# Switch to the new app
await switch_app("my_second_app")

# Send a notification using the current app
await send_notification(
    title="Hello", 
    message="This is from my second app"
)

# Send a notification from a specific app (without switching)
await send_notification(
    title="Hello", 
    message="This is from my first app", 
    app_key="mandible"
)

セグメントの管理

# List all segments
segments = await view_segments()
print(segments)

# Create a new segment
result = await create_segment(
    name="High Value Users",
    filters='[{"field":"amount_spent", "relation":">", "value":"100"}]'
)
print(result)

テンプレートの操作

# Create an email template
result = await create_template(
    name="Welcome Email",
    title="Welcome to Our App",
    message="<html><body><h1>Welcome!</h1><p>Thank you for joining us.</p></body></html>",
    template_type="email"
)
print(result)

マルチアプリサポート

このサーバーは複数のOneSignalアプリケーションの管理をサポートしています。以下のことが可能です。

異なる識別子を持つ複数のアプリ構成を追加する
API呼び出し時にアプリを切り替える
個々の操作に使用するアプリを指定する

アプリ管理ツール

list_apps : サーバーに設定されているすべてのOneSignalアプリを一覧表示します
add_app : 新しいOneSignalアプリ設定を追加する
update_app : 既存のOneSignalアプリの設定を更新する
remove_app : OneSignal アプリの設定を削除します
switch_app : APIリクエストに使用する現在のアプリを切り替える

利用可能なツール

メッセージ管理

send_notification : 新しいプッシュ通知、メール、またはSMSを送信する
view_messages : OneSignal 経由で送信された最近のメッセージを一覧表示します
view_message_details : 特定のメッセージに関する詳細情報を取得する
cancel_message : スケジュールされたメッセージをキャンセルする

デバイス管理

view_devices : OneSignal アプリに登録されているデバイス（ユーザー）を一覧表示します
view_device_details : 特定のデバイスに関する詳細情報を取得する

セグメント管理

view_segments : OneSignal アプリで利用可能なすべてのセグメントを一覧表示します
create_segment : 指定されたフィルターで新しいセグメントを作成する
delete_segment : 既存のセグメントを削除する

テンプレート管理

view_templates : OneSignal アプリで利用可能なすべてのテンプレートを一覧表示します
view_template_details : 特定のテンプレートの詳細情報を取得する
create_template : 通知やメール用の新しいテンプレートを作成する

アプリ情報

view_app_details : 設定されたOneSignalアプリの詳細情報を取得します

ログ記録

サーバーには、デバッグと監視を支援する包括的なログ機能が搭載されています。ログはデフォルトで以下の形式でコンソールに出力されます。

YYYY-MM-DD HH:MM:SS - onesignal-mcp - LEVEL - Message

サーバーファイルのlogging.basicConfig呼び出しを変更することで、ログレベルを調整できます。

テスト

OneSignal MCPサーバーには、すべての機能が期待どおりに動作することを確認するための包括的なテストスイートが含まれています。これらのテストでは、Pythonの組み込みunittestフレームワークと外部API呼び出しのモックを使用して、サーバーの動作をテストします。

テストの実行

テストを実行するには、次のコマンドを使用します。

python -m unittest discover tests

これにより、 testsディレクトリ内のすべてのテストが検出され、実行されます。

テスト範囲

テストスイートは以下をカバーします。

アプリ構成管理
適切な認証によるAPIリクエスト処理
エラー処理と回復
複数のアプリのサポート
組織レベルの運用

新しいテストを書く

サーバーに新しい機能を追加する場合は、対応するテストも追加してください。テストはtestsディレクトリに配置し、 test_*.py命名規則に従ってください。

トラブルシューティング

よくある問題

利用可能なアプリ構成がありません

「アプリ構成が利用できません」というエラーが表示された場合は、次のことを確認してください。

正しい資格情報を使用して.envファイルを設定するか、
add_appツールを使用してアプリ構成を追加しました

APIキーエラー

認証エラーが発生した場合は、次の点を確認してください。

APIキーは正しいです
操作に適切なキーを使用しています (REST API キーと組織 API キー)
キーにはOneSignalに必要な権限があります

レート制限

OneSignalではAPIリクエストにレート制限があります。レート制限が発生した場合は、以下の手順に従ってください。

リクエストの頻度を減らす
指数バックオフによる再試行ロジックを実装する

ヘルプの取得

ここで説明されていない問題が発生した場合:

OneSignal APIドキュメントを確認する
GitHubリポジトリで問題を開く

貢献

OneSignal MCP サーバーの改善に向けた貢献を歓迎します。ガイドラインについてはCONTRIBUTING.md をご覧ください。

ライセンス

このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細についてはLICENSEファイルを参照してください。

謝辞

優れた通知サービスとAPIを提供するOneSignal
このプロジェクトを支援してくれたWeirdbrainsチーム

OneSignal MCP Server

Integrations