OneSignal MCP Server
A comprehensive Model Context Protocol (MCP) server for interacting with the OneSignal API. This server provides a complete interface for managing push notifications, emails, SMS, users, devices, segments, templates, analytics, and more through OneSignal's REST API.
Overview
This MCP server provides comprehensive access to the OneSignal REST API, offering 57 tools that cover all major OneSignal operations:
🚀 Key Features
- Multi-channel Messaging: Send push notifications, emails, SMS, and transactional messages
- User & Device Management: Complete CRUD operations for users, devices, and subscriptions
- Advanced Segmentation: Create and manage user segments with complex filters
- Template System: Create, update, and manage message templates
- iOS Live Activities: Full support for iOS Live Activities
- Analytics & Export: View outcomes data and export to CSV
- Multi-App Support: Manage multiple OneSignal applications seamlessly
- API Key Management: Create, update, rotate, and delete API keys
- Organization-level Operations: Manage apps across your entire organization
Requirements
- Python 3.7 or higher
python-dotenvpackagerequestspackagemcppackage- OneSignal account with API credentials
Installation
Option 1: Clone from GitHub
# Clone the repository
git clone https://github.com/weirdbrains/onesignal-mcp.git
cd onesignal-mcp
# Install dependencies
pip install -r requirements.txt
Option 2: Install as a Package (Coming Soon)
pip install onesignal-mcp
Configuration
-
Create a
.envfile in the root directory with your OneSignal credentials:# 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 -
Find your OneSignal credentials:
- App ID: Settings > Keys & IDs > OneSignal App ID
- REST API Key: Settings > Keys & IDs > REST API Key
- Organization API Key: Organization Settings > API Keys
Usage
Running the Server
python onesignal_server.py
The server will start and register itself with the MCP system, making all 57 tools available for use.
Complete Tools Reference (57 Tools)
📱 App Management (5 tools)
list_apps- List all configured OneSignal appsadd_app- Add a new OneSignal app configuration locallyupdate_local_app_config- Update an existing local app configurationremove_app- Remove a local OneSignal app configurationswitch_app- Switch the current app to use for API requests
📨 Messaging (8 tools)
send_push_notification- Send a push notificationsend_email- Send an email through OneSignalsend_sms- Send an SMS/MMS through OneSignalsend_transactional_message- Send immediate delivery messagesview_messages- View recent messages sentview_message_details- Get detailed information about a messageview_message_history- View message history/recipientscancel_message- Cancel a scheduled message
📱 Devices/Players (6 tools)
view_devices- View devices subscribed to your appview_device_details- Get detailed information about a deviceadd_player- Add a new player/deviceedit_player- Edit an existing player/devicedelete_player- Delete a player/device recordedit_tags_with_external_user_id- Bulk edit tags by external ID
🎯 Segments (3 tools)
view_segments- List all segmentscreate_segment- Create a new segmentdelete_segment- Delete a segment
📄 Templates (6 tools)
view_templates- List all templatesview_template_details- Get template detailscreate_template- Create a new templateupdate_template- Update an existing templatedelete_template- Delete a templatecopy_template_to_app- Copy template to another app
🏢 Apps (6 tools)
view_app_details- Get details about configured appview_apps- List all organization appscreate_app- Create a new OneSignal applicationupdate_app- Update an existing applicationview_app_api_keys- View API keys for an appcreate_app_api_key- Create a new API key
🔑 API Key Management (3 tools)
delete_app_api_key- Delete an API keyupdate_app_api_key- Update an API keyrotate_app_api_key- Rotate an API key
👤 Users (6 tools)
create_user- Create a new userview_user- View user detailsupdate_user- Update user informationdelete_user- Delete a userview_user_identity- Get user identity informationview_user_identity_by_subscription- Get identity by subscription
🏷️ Aliases (3 tools)
create_or_update_alias- Create or update user aliasdelete_alias- Delete a user aliascreate_alias_by_subscription- Create alias by subscription ID
📬 Subscriptions (5 tools)
create_subscription- Create a new subscriptionupdate_subscription- Update a subscriptiondelete_subscription- Delete a subscriptiontransfer_subscription- Transfer subscription between usersunsubscribe_email- Unsubscribe using email token
🎯 Live Activities (3 tools)
start_live_activity- Start iOS Live Activityupdate_live_activity- Update iOS Live Activityend_live_activity- End iOS Live Activity
📊 Analytics & Export (3 tools)
view_outcomes- View outcomes/conversion dataexport_players_csv- Export player data to CSVexport_messages_csv- Export messages to CSV
Usage Examples
Multi-Channel Messaging
# 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=["user@example.com"]
)
# 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"]}
)
User and Device Management
# Create a user
user = await create_user(
name="John Doe",
email="john@example.com",
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 Live Activities
# 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"}
)
Analytics and Export
# 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"]
)
Testing
The server includes a comprehensive test suite. To run tests:
# Run the test script
python test_onesignal_mcp.py
# Or use unittest
python -m unittest discover tests
Error Handling
The server provides consistent error handling:
- All errors are returned in a standardized format
- Detailed error messages help identify issues
- Automatic retry logic for transient failures
- Proper authentication error messages
Rate Limiting
OneSignal enforces rate limits on API requests:
- Standard limit: 10 requests per second
- Bulk operations: May have lower limits
- The server includes guidance on handling rate limits
Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgements
- OneSignal for their excellent notification service
- The MCP community for the Model Context Protocol
- All contributors to this project