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.
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
- Log in to your OneSignal Dashboard
- Go to Settings > Keys & IDs
- Copy your App ID and REST API Key (format:
os_v2_app_xxxxx) - (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_oros_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.