Skip to main content
Glama
enesjakozh
WeirdBrains

OneSignal MCP Server

by WeirdBrains
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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.

License: MIT Version Tools

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

Related MCP server: MCP Boilerplate

Requirements

  • Python 3.7 or higher

  • python-dotenv package

  • requests package

  • mcp package

  • 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

  1. 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

  2. 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 apps

  • add_app - Add a new OneSignal app configuration locally

  • update_local_app_config - Update an existing local app configuration

  • remove_app - Remove a local OneSignal app configuration

  • switch_app - Switch the current app to use for API requests

📨 Messaging (8 tools)

  • send_push_notification - Send a push notification

  • send_email - Send an email through OneSignal

  • send_sms - Send an SMS/MMS through OneSignal

  • send_transactional_message - Send immediate delivery messages

  • view_messages - View recent messages sent

  • view_message_details - Get detailed information about a message

  • view_message_history - View message history/recipients

  • cancel_message - Cancel a scheduled message

📱 Devices/Players (6 tools)

  • view_devices - View devices subscribed to your app

  • view_device_details - Get detailed information about a device

  • add_player - Add a new player/device

  • edit_player - Edit an existing player/device

  • delete_player - Delete a player/device record

  • edit_tags_with_external_user_id - Bulk edit tags by external ID

🎯 Segments (3 tools)

  • view_segments - List all segments

  • create_segment - Create a new segment

  • delete_segment - Delete a segment

📄 Templates (6 tools)

  • view_templates - List all templates

  • view_template_details - Get template details

  • create_template - Create a new template

  • update_template - Update an existing template

  • delete_template - Delete a template

  • copy_template_to_app - Copy template to another app

🏢 Apps (6 tools)

  • view_app_details - Get details about configured app

  • view_apps - List all organization apps

  • create_app - Create a new OneSignal application

  • update_app - Update an existing application

  • view_app_api_keys - View API keys for an app

  • create_app_api_key - Create a new API key

🔑 API Key Management (3 tools)

  • delete_app_api_key - Delete an API key

  • update_app_api_key - Update an API key

  • rotate_app_api_key - Rotate an API key

👤 Users (6 tools)

  • create_user - Create a new user

  • view_user - View user details

  • update_user - Update user information

  • delete_user - Delete a user

  • view_user_identity - Get user identity information

  • view_user_identity_by_subscription - Get identity by subscription

🏷️ Aliases (3 tools)

  • create_or_update_alias - Create or update user alias

  • delete_alias - Delete a user alias

  • create_alias_by_subscription - Create alias by subscription ID

📬 Subscriptions (5 tools)

  • create_subscription - Create a new subscription

  • update_subscription - Update a subscription

  • delete_subscription - Delete a subscription

  • transfer_subscription - Transfer subscription between users

  • unsubscribe_email - Unsubscribe using email token

🎯 Live Activities (3 tools)

  • start_live_activity - Start iOS Live Activity

  • update_live_activity - Update iOS Live Activity

  • end_live_activity - End iOS Live Activity

📊 Analytics & Export (3 tools)

  • view_outcomes - View outcomes/conversion data

  • export_players_csv - Export player data to CSV

  • export_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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/WeirdBrains/onesignal-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server