OneSignal MCP Server

# OneSignal MCP Server A comprehensive Model Context Protocol (MCP) server for OneSignal push notifications, email, SMS, and user management. Enables AI assistants to interact with OneSignal through natural language. [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io) ## Features - **50+ tools** for complete OneSignal API coverage - **Multi-channel messaging**: Push notifications, email, SMS/MMS - **User management**: Create, update, delete users and subscriptions - **Segmentation**: Dynamic targeting with filters and segments - **Templates**: Reusable message templates - **iOS Live Activities**: Start, update, and end Live Activities - **Analytics**: View outcomes, export data, track custom events - **Multi-app support**: Manage multiple OneSignal apps ## Quick Start ### Prerequisites - Python 3.10+ - [uv](https://github.com/astral-sh/uv) package manager (recommended) or pip - OneSignal account with API credentials ### Installation ```bash git clone https://github.com/chansearrington/onesignal-mcp.git cd onesignal-mcp ``` ### Get Your OneSignal Credentials 1. Log in to your [OneSignal Dashboard](https://dashboard.onesignal.com) 2. Go to **Settings > Keys & IDs** 3. Copy your **App ID** and **REST API Key** (format: `os_v2_app_xxxxx`) 4. (Optional) For org-level operations, get your **Organization API Key** from **Organization Settings > API Keys** ## Client Setup ### Claude Desktop Add to your `~/.claude.json`: ```json { "mcpServers": { "onesignal": { "type": "stdio", "command": "uv", "args": [ "run", "--with", "mcp", "--with", "python-dotenv", "--with", "requests", "/path/to/onesignal-mcp/onesignal_server.py" ], "env": { "ONESIGNAL_APP_ID": "your-app-id", "ONESIGNAL_API_KEY": "os_v2_app_your-api-key" } } } } ``` ### Claude Code (CLI) Add to your `~/.claude/settings.json`: ```json { "mcpServers": { "onesignal": { "type": "stdio", "command": "uv", "args": [ "run", "--with", "mcp", "--with", "python-dotenv", "--with", "requests", "/path/to/onesignal-mcp/onesignal_server.py" ], "env": { "ONESIGNAL_APP_ID": "your-app-id", "ONESIGNAL_API_KEY": "os_v2_app_your-api-key" } } } } ``` ### Cursor Add to your `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally: ```json { "mcpServers": { "onesignal": { "command": "uv", "args": [ "run", "--with", "mcp", "--with", "python-dotenv", "--with", "requests", "/path/to/onesignal-mcp/onesignal_server.py" ], "env": { "ONESIGNAL_APP_ID": "your-app-id", "ONESIGNAL_API_KEY": "os_v2_app_your-api-key" } } } } ``` ### VS Code (with Continue or GitHub Copilot) Add to your `.vscode/mcp.json`: ```json { "mcpServers": { "onesignal": { "command": "uv", "args": [ "run", "--with", "mcp", "--with", "python-dotenv", "--with", "requests", "${workspaceFolder}/onesignal_server.py" ], "env": { "ONESIGNAL_APP_ID": "your-app-id", "ONESIGNAL_API_KEY": "os_v2_app_your-api-key" } } } } ``` ### Alternative: Using .env File Instead of setting credentials in the config, create a `.env` file: ```bash cp .env.example .env # Edit .env with your credentials ``` Then simplify your MCP config: ```json { "mcpServers": { "onesignal": { "command": "uv", "args": ["run", "--with", "mcp", "--with", "python-dotenv", "--with", "requests", "/path/to/onesignal_server.py"], "cwd": "/path/to/onesignal-mcp" } } } ``` ## Available Tools ### Messaging | Tool | Description | |------|-------------| | `send_push_notification` | Send basic push notification | | `send_advanced_push_notification` | Push with scheduling, images, buttons, filters | | `send_email` | Send basic email | | `send_advanced_email` | Email with HTML, scheduling, custom sender | | `send_sms` | Send SMS/MMS | | `send_advanced_sms` | SMS with scheduling, media, filters | | `send_transactional_message` | Immediate transactional message | ### Message Management | Tool | Description | |------|-------------| | `view_messages` | List recent messages | | `view_message_details` | Get message details | | `view_message_history` | View delivery/click history | | `cancel_message` | Cancel scheduled message | | `export_audience_activity` | Export engagement CSV | ### Users & Subscriptions | Tool | Description | |------|-------------| | `create_user` | Create user with identity | | `view_user` | Get user details | | `update_user` | Update user tags/properties | | `delete_user` | Delete user | | `create_subscription` | Add email/SMS/push subscription | | `update_subscription` | Enable/disable subscription | | `delete_subscription` | Remove subscription | | `transfer_subscription` | Move to another user | ### Segments & Templates | Tool | Description | |------|-------------| | `view_segments` | List segments | | `create_segment` | Create segment with filters | | `delete_segment` | Delete segment | | `view_templates` | List templates | | `create_template` | Create template | | `update_template` | Update template | | `delete_template` | Delete template | ### iOS Live Activities | Tool | Description | |------|-------------| | `start_live_activity` | Start Live Activity | | `start_live_activity_advanced` | Start with full options | | `update_live_activity` | Update running activity | | `end_live_activity` | End activity | ### Analytics & Events | Tool | Description | |------|-------------| | `view_outcomes` | View click/conversion metrics | | `create_custom_events` | Track user events for Journeys | | `export_messages_csv` | Export message data | ### App Management | Tool | Description | |------|-------------| | `list_apps` | List configured apps | | `switch_app` | Switch current app | | `add_app` | Add app configuration | | `view_app_details` | Get app info | | `view_app_api_keys` | List API keys | | `create_app_api_key` | Create new API key | | `rotate_app_api_key` | Rotate API key | ## Usage Examples ### Send a Push Notification ``` "Send a push notification with title 'Hello!' and message 'Welcome to our app'" ``` ### Target Specific Users ``` "Send a push notification to users with external_id user_123 and user_456" ``` ### Schedule a Message ``` "Send a push notification tomorrow at 9am saying 'Good morning!' to the Daily Digest segment" ``` ### Create a User ``` "Create a user with external_id 'customer_789', email 'user@example.com', and tags plan=premium, signup_date=2024-01-15" ``` ### Track Events ``` "Track a purchase event for user customer_789 with amount 99.99 and product_id SKU-123" ``` ## Configuration Options | Variable | Required | Description | |----------|----------|-------------| | `ONESIGNAL_APP_ID` | Yes | Your OneSignal App ID | | `ONESIGNAL_API_KEY` | Yes | REST API Key (format: `os_v2_app_xxx`) | | `ONESIGNAL_ORG_API_KEY` | No | Organization API Key for org-level operations | | `LOG_LEVEL` | No | Logging level (DEBUG, INFO, WARNING, ERROR) | ## Troubleshooting ### "No app currently selected" Make sure your `ONESIGNAL_APP_ID` and `ONESIGNAL_API_KEY` are set correctly. ### "Organization API Key not configured" Some operations (like `view_apps`, `create_app_api_key`) require the `ONESIGNAL_ORG_API_KEY`. ### API Errors - Verify your API key format starts with `os_v2_app_` or `os_v2_org_` - Check that your API key has the necessary permissions in OneSignal dashboard - Ensure your App ID is correct (UUID format) ## Credits This project is based on [WeirdBrains/onesignal-mcp](https://github.com/WeirdBrains/onesignal-mcp). Special thanks for the original implementation. ## License MIT License - see [LICENSE](LICENSE) file for details. ## Links - [OneSignal Documentation](https://documentation.onesignal.com/) - [Model Context Protocol](https://modelcontextprotocol.io/) - [OneSignal Dashboard](https://dashboard.onesignal.com/)