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

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

• OneSignal Documentation
• Model Context Protocol
• OneSignal Dashboard