# OneSignal MCP

> OneSignal MCP Server connects your AI agent directly to OneSignal's full suite of marketing and communication tools. Send targeted push notifications, manage complex user segments, dispatch emails, and track delivery metrics—all from a single chat interface. Manage player data and campaign outcomes without ever logging into the OneSignal dashboard.

## Overview
- **Category:** industry-titans
- **Price:** Free
- **Tags:** onesignal, push-notifications, omnichannel-marketing, sms-api, email-automation, user-segmentation, engagement-analytics, growth-ops, mcp

## Description

**OneSignal MCP Server** lets your AI client talk directly to OneSignal’s entire communication stack. You can send targeted alerts, check user profiles, and audit campaign results without ever opening the OneSignal dashboard. It gives you complete control over your push notifications, segments, and player data straight from your chat interface.

### Dispatching Targeted Notifications

You use the `send_push_notification` tool to immediately send proactive alerts to specific groups or lists of players. Before sending anything out, you can check which target audiences are available by calling `list_app_segments`; this function shows you all the pre-built user segments in your account so you know exactly who you're hitting. You also get a comprehensive list of every active device ID that’s subscribed to your app using `list_app_players`, ensuring nobody gets left behind.

### Managing and Querying Player Data

If you need details on an individual user, the `get_player_details` tool pulls up the complete profile and all metadata for one specific device ID. Need a full list of those players? You use `list_app_players` again to pull that master roster. If a player moves or leaves, you can permanently wipe their record from your system using `remove_player`. The server also lets you check the overall connection status and health of the OneSignal API integration by running `get_api_status`, so you know if everything's up and running.

### Auditing Campaign Performance and History

You don’t just send messages; you track them. After a campaign runs, you can pull detailed delivery metrics—like how many users opened the message or what the click-through rate was—by calling `get_notification_stats` using a specific notification ID. You also get the final business outcome of large campaigns by running `list_app_outcomes`, which reports on the overall results for those sends. To see recent activity, use `list_recent_notifications`; this shows you a list of both the most recently sent alerts and any broadcasts that are scheduled to go out later.

### Controlling Scheduled Sends and Setup Checks

You gotta manage future blasts, too. If something needs to change, you can cancel an alert that was set to send at a specific time using `cancel_scheduled_alert`. Before relying on the system, you can get general information about your connected OneSignal application setup with `get_app_details`, or if your account manages multiple apps, you use `list_onesignal_apps` (which requires a User Auth Key) to see everything connected. This server lets your agent handle every part of your communication stack—from listing all available segments via `list_app_segments` right down to checking the API status with `get_api_status`. You've got full control over sending, tracking, and cleaning up user data without leaving your chat client.

## Tools

### cancel_scheduled_alert
Stops a notification that was scheduled to send out at a specific time.

### send_push_notification
Sends an immediate, proactive push notification to a specified segment or list of players.

### remove_player
Permanently deletes a specific user's device record from your active player database.

### get_api_status
Checks the current connection status and health of the OneSignal API integration.

### get_app_details
Retrieves general information about your connected OneSignal application setup.

### get_notification_stats
Pulls detailed delivery metrics (opens, clicks) for a specific notification ID.

### get_player_details
Retrieves the complete profile and metadata for a single user device ID.

### list_onesignal_apps
Requires a User Auth Key. Lists all OneSignal applications connected under an account.

### list_recent_notifications
Shows a list of the most recently sent or scheduled notification broadcasts.

### list_app_outcomes
Lists final outcomes or results from specific marketing campaigns run through OneSignal.

### list_app_segments
Lists and describes the various pre-defined user groups or target segments available in your account.

### list_app_players
Retrieves a list of all active device IDs that are currently subscribed to your app.

## Prompt Examples

**Prompt:** 
```
List the last 5 push notifications sent from OneSignal.
```

**Response:** 
```
I've retrieved your notification history. You have 5 recent broadcasts including 'Black Friday Launch' (Status: Sent) and 'App Update'. Would you like to see the click-through rates for any of them?
```

**Prompt:** 
```
Send a push notification to the segment named VIP Users with a promotional message.
```

**Response:** 
```
Push notification sent successfully to the "VIP Users" segment. 4,287 devices targeted across iOS (2,103) and Android (2,184). The message "Exclusive early access to our summer collection is live" was delivered with a deep link to your promotion page. Estimated delivery time: under 30 seconds.
```

**Prompt:** 
```
Show me the delivery and click-through analytics for notification ID ntf_8923.
```

**Response:** 
```
Notification ntf_8923 "Flash Sale Alert" was sent to 12,450 subscribers. Delivered: 11,892 (95.5%). Opened: 3,214 (27% CTR). Clicked: 1,847 (14.8% click rate). iOS performed better with 31% CTR versus Android at 24%. Peak engagement was within the first 15 minutes after delivery.
```

## Capabilities

### Dispatch targeted alerts
Send immediate push notifications, emails, or SMS messages to specific user segments.

### Manage and query player data
Retrieve detailed profiles for individual users (players) and manage their device records.

### Define and filter audiences
List, check, and apply dynamic targeting criteria to your subscriber groups (segments).

### Audit campaign performance
Pull detailed delivery metrics, including open rates, click-through rates, and failure counts for past sends.

### Control scheduled broadcasts
List recent notifications or cancel alerts that are set to go out at a later time.

## Use Cases

### Running an emergency alert
The support team needs to warn users about a critical bug. Instead of manually listing every affected user ID, they ask their agent: 'Send a push notification using the segment named 'Beta Testers' with this message.' The agent executes `send_push_notification` immediately, reaching all 4,500 targeted devices in seconds.

### Investigating low engagement
The growth manager sees that the last email campaign underperformed. They ask their agent to 'Check the metrics for notification ID ntf_8923.' The agent calls `get_notification_stats`, reports back that the click rate was only 14.8%, and helps the team determine if the targeting needs adjusting.

### Cleaning up stale data
The product owner identifies a group of users who haven't logged in for six months. They first call `get_player_details` on three sample IDs to verify metadata, then use the agent to identify and execute `remove_player` calls across all inactive accounts, keeping the database clean.

### Verifying segment structure
Before launching a major promotion, the marketing lead needs to know if their target group is defined correctly. They ask the agent to 'List all available segments,' which calls `list_app_segments`, allowing them to verify that the 'High-Value Customers' tag actually exists and has enough users.

## Benefits

- Run full campaign audits without switching apps. Use `get_notification_stats` to instantly pull metrics like open rates and click-through rates for any notification ID, giving you immediate performance feedback.
- Target users with precision. Instead of guessing, use `list_app_segments` to see your existing groups, then run `send_push_notification` on a defined segment—no manual list building required.
- Maintain clean user data. If a player leaves or changes devices, you can run `get_player_details` first and then execute `remove_player` to keep your CRM accurate.
- Automate alerts and cleanup. Use `cancel_scheduled_alert` if a sale ends early, or use `list_recent_notifications` to quickly check what went out yesterday.
- Understand campaign success. If you run a major marketing push, call `list_app_outcomes` to see the final business result tied to that specific promotion.

## How It Works

The bottom line is: your AI client acts as an instant growth operations manager, letting you handle complex marketing tasks without ever opening multiple tabs or manually copying IDs.

1. Subscribe to the server and enter your OneSignal App ID and REST API Key into your AI client.
2. Ask your agent to perform an action, like 'Show me the performance metrics for campaign X.'
3. The agent calls the relevant tool (e.g., `get_notification_stats`), processes the data, and gives you a plain-text summary in the chat.

## Frequently Asked Questions

**How do I check if my connection is working with get_api_status?**
Run `get_api_status` first. It confirms your credentials and API key are valid, telling you immediately if the server can communicate with OneSignal.

**What should I use to send a message to only 'VIP' users?**
Use `list_app_segments` first to confirm the 'VIP' segment exists. Then, call `send_push_notification`, referencing that confirmed segment ID for accurate targeting.

**Can I delete a user record using remove_player?**
Yes, this tool permanently deletes a specific device ID from your player list. Use it when you know the user has abandoned the platform and their data needs to be scrubbed for compliance.

**How do I view past alerts using list_recent_notifications?**
Run `list_recent_notifications` to see a history of all broadcasts. This gives you IDs you can then pass into the `get_notification_stats` tool for detailed performance analysis.

**How do I use `list_onesignal_apps` to check my account connections?**
You must pass your User Auth Key to successfully list applications. This tool pulls a manifest of all OneSignal apps linked to your account, verifying which services are available for management through the server.

**What specific metrics does `list_app_outcomes` provide for campaigns?**
This function retrieves deep performance data beyond simple counts. You get campaign outcomes like conversion rates and revenue attribution, allowing you to measure true business impact rather than just engagement volume.

**How do I retrieve detailed user information using `get_player_details`?**
The tool pulls a comprehensive record for any player ID. It includes the device metadata (iOS/Android), custom tags, and last activity timestamp, giving you enough context to target highly specific groups.

**What is the purpose of `cancel_scheduled_alert`?**
You pass a unique alert ID to stop any pending notification immediately. This feature lets you correct mistakes or pull back an unintended broadcast before it reaches users.

**Can my AI automatically find the Player ID for a specific user to send a test push?**
Yes! Use the `list_users` tool. Your agent will respond with complete metadata for registered devices, including unique Player IDs and tags, allowing you to trigger targeted pushes instantly.

**How do I find my OneSignal App ID and REST API Key?**
Log in to OneSignal, select your app, navigate to **Settings** > **Keys & IDs**, and you will find your unique App ID and secret REST API key there.

**Can I use the AI to cancel a scheduled notification?**
Absolutely. Use the `cancel_notification` tool with the Notification ID. The agent will instruct OneSignal to stop the broadcast immediately, provided it hasn't been fully delivered yet.