Skip to main content
Glama
chansearrington

OneSignal MCP Server

by chansearrington
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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.

License: MIT Python 3.10+ MCP

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 package manager (recommended) or pip

  • OneSignal account with API credentials

Installation

git clone https://github.com/chansearrington/onesignal-mcp.git cd onesignal-mcp

Get Your OneSignal Credentials

  1. Log in to your OneSignal Dashboard

  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:

{ "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:

{ "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:

{ "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:

{ "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:

cp .env.example .env # Edit .env with your credentials

Then simplify your MCP config:

{ "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. Special thanks for the original implementation.

License

MIT License - see LICENSE file for details.

Links

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

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/chansearrington/OneSignal-MCP'

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