OneSignal MCP Server

How to use

To use this MCP server, start the local Python process and connect to it with an MCP client. The server presents 57 tools you can call to manage OneSignal resources and actions, such as creating apps, sending push notifications, managing users and devices, building segments, handling templates, and exporting analytics.

How to install

Prerequisites you need before installing this MCP server:

• Python 3.7 or higher
• pip (Python package installer)
• python-dotenv package
• requests package
• mcp package
• OneSignal account with API credentials

Option 1 — Clone and install dependencies directly in your environment:

# 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 (when available):

pip install onesignal-mcp

Prepare your environment file with credentials (see Configuration for details). After installation, you can start the server with the Python script provided in the project.

Additional sections

Configuration, security, and troubleshooting details are provided to help you run reliably in development or production. You will set up environment variables, start the server, and verify that all 57 tools are available for use.

Note the server will register itself with the MCP system when you start it, making all tools available to your MCP client.

Configuration

Create a .env file in your project root with your OneSignal credentials. You can configure multiple app profiles for multi-app deployments.

# Default app credentials (optional)
ONESIGNAL_APP_ID=your_app_id_here
ONESIGNAL_API_KEY=your_rest_api_key_here

# Organization-level API key (for org-wide 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
LOG_LEVEL=INFO

Starting the MCP server

Run the server using the Python runtime. This starts the MCP server and exposes all configured tools for use by your MCP client.

python onesignal_server.py

Security and credentials

Protect your API credentials and environment keys. Use secure storage for your .env file and restrict access to systems running the MCP server. Rotate keys periodically and apply principle of least privilege to your client applications.

Examples and tips

When you build client code, reference the tools by their names, such as: view_user, create_app, send_push_notification, start_live_activity, and view_outcomes. Use the available methods to orchestrate multi-channel messages, manage users and devices, build segments, and export data for reporting.

Troubleshooting

If you encounter authentication errors, verify that ONESIGNAL_APP_ID and ONESIGNAL_API_KEY are correctly set in your environment. For connection or rate-limiting issues, review your request patterns and respect standard MCP rate limits. Check that the server process is running and that the .env file is accessible to the running process.

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 used for API requests

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

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

view_segments

List all segments

create_segment

Create a new segment

delete_segment

Delete a segment

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

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

delete_app_api_key

Delete an API key

update_app_api_key

Update an API key

rotate_app_api_key

Rotate an API key

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

create_or_update_alias

Create or update user alias

delete_alias

Delete a user alias

create_alias_by_subscription

Create alias by subscription ID

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

start_live_activity

Start iOS Live Activity

update_live_activity

Update iOS Live Activity

end_live_activity

End iOS Live Activity

view_outcomes

View outcomes/conversion data

export_players_csv

Export player data to CSV

export_messages_csv

Export messages to CSV