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.
- 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
- Python 3.10+
- uv package manager (recommended) or pip
- OneSignal account with API credentials
git clone https://github.com/chansearrington/onesignal-mcp.git
cd onesignal-mcp- 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
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"
}
}
}
}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"
}
}
}
}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"
}
}
}
}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"
}
}
}
}Instead of setting credentials in the config, create a .env file:
cp .env.example .env
# Edit .env with your credentialsThen 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"
}
}
}| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| Tool | Description |
|---|---|
view_outcomes |
View click/conversion metrics |
create_custom_events |
Track user events for Journeys |
export_messages_csv |
Export message data |
| 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 |
"Send a push notification with title 'Hello!' and message 'Welcome to our app'"
"Send a push notification to users with external_id user_123 and user_456"
"Send a push notification tomorrow at 9am saying 'Good morning!' to the Daily Digest segment"
"Create a user with external_id 'customer_789', email 'user@example.com', and tags plan=premium, signup_date=2024-01-15"
"Track a purchase event for user customer_789 with amount 99.99 and product_id SKU-123"
| 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) |
Make sure your ONESIGNAL_APP_ID and ONESIGNAL_API_KEY are set correctly.
Some operations (like view_apps, create_app_api_key) require the ONESIGNAL_ORG_API_KEY.
- 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)
This project is based on WeirdBrains/onesignal-mcp. Special thanks for the original implementation.
MIT License - see LICENSE file for details.