How do I use OneSignal MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OneSignal MCP Server send a push notification to all iOS users about our new feature launch" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

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_ 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.

OneSignal MCP Server

OneSignal MCP Server

Features

Quick Start

Prerequisites

Installation

Get Your OneSignal Credentials

Client Setup

Claude Desktop

Claude Code (CLI)

Cursor

VS Code (with Continue or GitHub Copilot)

Alternative: Using .env File

Available Tools

Messaging

Message Management

Users & Subscriptions

Segments & Templates

iOS Live Activities

Analytics & Events

App Management

Usage Examples

Send a Push Notification

Target Specific Users

Schedule a Message

Create a User

Track Events

Configuration Options

Troubleshooting

"No app currently selected"

"Organization API Key not configured"

API Errors

Credits

License

Links

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API