A Model Context Protocol (MCP) server for interacting with the OneSignal API
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.
This MCP server provides comprehensive access to the OneSignal REST API, offering 57 tools that cover all major OneSignal operations:
python-dotenv packagerequests packagemcp package## Clone the repository
git clone https://github.com/weirdbrains/onesignal-mcp.git
cd onesignal-mcp
## Install dependencies
pip install -r requirements.txt
pip install onesignal-mcp
Create a .env file 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_MANDIBLE_APP_ID=mandible_app_id
ONESIGNAL_MANDIBLE_API_KEY=mandible_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:
python onesignal_server.py
The server will start and register itself with the MCP system, making all 57 tools available for use.
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 requestssend_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 messageview_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 IDview_segments - List all segmentscreate_segment - Create a new segmentdelete_segment - Delete a segmentview_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 appview_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 keydelete_app_api_key - Delete an API keyupdate_app_api_key - Update an API keyrotate_app_api_key - Rotate an API keycreate_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 subscriptioncreate_or_update_alias - Create or update user aliasdelete_alias - Delete a user aliascreate_alias_by_subscription - Create alias by subscription IDcreate_subscription - Create a new subscriptionupdate_subscription - Update a subscriptiondelete_subscription - Delete a subscriptiontransfer_subscription - Transfer subscription between usersunsubscribe_email - Unsubscribe using email tokenstart_live_activity - Start iOS Live Activityupdate_live_activity - Update iOS Live Activityend_live_activity - End iOS Live Activityview_outcomes - View outcomes/conversion dataexport_players_csv - Export player data to CSVexport_messages_csv - Export messages to 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"}
)
## 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"]
)
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
The server provides consistent error handling:
OneSignal enforces rate limits on API requests:
We welcome contributions! Please see CONTRIBUTING.md{:target=“_blank”} for guidelines.
This project is licensed under the MIT License - see the LICENSE{:target=“_blank”} file for details.
A Model Context Protocol (MCP) server for querying the CVE-Search API
A Model Context Protocol server for SMTP email services
An MCP server implementation that integrates the Tavily Search API, providing optimized search capabilities for LLMs.
