# 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](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)

## 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](https://github.com/astral-sh/uv) package manager (recommended) or pip
- OneSignal account with API credentials

### Installation

```bash
git clone https://github.com/chansearrington/onesignal-mcp.git
cd onesignal-mcp
```

### Get Your OneSignal Credentials

1. Log in to your [OneSignal Dashboard](https://dashboard.onesignal.com)
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`:

```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`:

```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:

```json
{
  "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`:

```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:

```bash
cp .env.example .env
# Edit .env with your credentials
```

Then simplify your MCP config:

```json
{
  "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](https://github.com/WeirdBrains/onesignal-mcp). Special thanks for the original implementation.

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Links

- [OneSignal Documentation](https://documentation.onesignal.com/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [OneSignal Dashboard](https://dashboard.onesignal.com/)