OneSignal MCP Server

# OneSignal MCP Server - Technical Specification > Complete technical reference for the OneSignal MCP Server ## Overview The OneSignal MCP Server provides a Model Context Protocol interface to OneSignal's REST API, enabling AI assistants to manage push notifications, email, SMS, users, and more through natural language. **Version**: 2.1.0 **Python**: 3.10+ **License**: MIT ## Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ Claude / MCP Client │ └─────────────────────────────────────────────────────────────┘ │ │ MCP Protocol (stdio) ▼ ┌─────────────────────────────────────────────────────────────┐ │ OneSignal MCP Server │ │ ┌─────────────────────────────────────────────────────────┐│ │ │ FastMCP Framework ││ │ │ - Tool Registration ││ │ │ - Request/Response Handling ││ │ └─────────────────────────────────────────────────────────┘│ │ ┌─────────────────────────────────────────────────────────┐│ │ │ App Configuration Manager ││ │ │ - Multi-app support ││ │ │ - API key management ││ │ └─────────────────────────────────────────────────────────┘│ │ ┌─────────────────────────────────────────────────────────┐│ │ │ OneSignal API Client ││ │ │ - Authentication ││ │ │ - Request routing ││ │ └─────────────────────────────────────────────────────────┘│ └─────────────────────────────────────────────────────────────┘ │ │ HTTPS ▼ ┌─────────────────────────────────────────────────────────────┐ │ OneSignal REST API │ │ https://api.onesignal.com │ └─────────────────────────────────────────────────────────────┘ ``` ## API Endpoints ### Base URL ``` https://api.onesignal.com ``` ### Authentication **App-level operations** (most tools): ``` Authorization: Key os_v2_app_xxxxx ``` **Organization-level operations** (`view_apps`, `create_app_api_key`, etc.): ``` Authorization: Key os_v2_org_xxxxx ``` ### Key Endpoints Used | Endpoint | Method | Description | |----------|--------|-------------| | `/notifications` | POST | Send messages | | `/notifications` | GET | List messages | | `/notifications/{id}` | GET | View message | | `/notifications/{id}` | DELETE | Cancel message | | `/notifications/{id}/history` | POST | Message history | | `/notifications/{id}/export_events` | POST | Export audience activity | | `/apps/{app_id}/users` | POST | Create user | | `/apps/{app_id}/users/by/{alias_label}/{alias_id}` | GET/PATCH/DELETE | User operations | | `/apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions` | POST | Create subscription | | `/apps/{app_id}/subscriptions/{id}` | PATCH/DELETE | Update/delete subscription | | `/apps/{app_id}/segments` | GET/POST | List/create segments | | `/apps/{app_id}/segments/{id}` | DELETE | Delete segment | | `/templates` | GET/POST | List/create templates | | `/templates/{id}` | GET/PATCH/DELETE | Template operations | | `/apps/{app_id}/custom_events` | POST | Create custom events | | `/apps/{app_id}/outcomes` | GET | View outcomes | ## Complete Tool Reference ### App Management (9 tools) | Tool | Description | API Key | |------|-------------|---------| | `list_apps` | List configured apps in server | N/A | | `add_app` | Add app configuration locally | N/A | | `update_local_app_config` | Update local app config | N/A | | `remove_app` | Remove local app config | N/A | | `switch_app` | Switch current app context | N/A | | `view_app_details` | View app details | Org | | `view_apps` | List all org apps | Org | | `create_app` | Create new app | Org | | `update_app` | Update app | Org | ### API Key Management (5 tools) | Tool | Description | API Key | |------|-------------|---------| | `view_app_api_keys` | List API keys for app | Org | | `create_app_api_key` | Create new API key | Org | | `update_app_api_key` | Update API key | Org | | `delete_app_api_key` | Delete API key | Org | | `rotate_app_api_key` | Rotate API key | Org | ### Push Notifications (2 tools) | Tool | Description | API Key | |------|-------------|---------| | `send_push_notification` | Basic push notification | App | | `send_advanced_push_notification` | Push with all options | App | **Advanced Push Options**: - Targeting: segments, external_ids, filters - Scheduling: send_after, delayed_option, delivery_time_of_day - Content: data, url, web_url, app_url - Images: big_picture, ios_attachments, chrome_web_image - Buttons: buttons, web_buttons - Delivery: ttl, priority, throttle_rate_per_minute - iOS: ios_badge_type, ios_badge_count, ios_sound - Android: android_channel_id, android_accent_color, android_led_color - Other: idempotency_key, name ### Email (2 tools) | Tool | Description | API Key | |------|-------------|---------| | `send_email` | Basic email | App | | `send_advanced_email` | Email with all options | App | **Advanced Email Options**: - Targeting: include_emails, external_ids, segments, filters - Content: email_body (HTML), email_preheader, template_id - Sender: email_from_name, email_from_address, email_reply_to_address - Scheduling: send_after - Tracking: disable_email_click_tracking ### SMS (2 tools) | Tool | Description | API Key | |------|-------------|---------| | `send_sms` | Basic SMS | App | | `send_advanced_sms` | SMS with all options | App | **Advanced SMS Options**: - Targeting: phone_numbers, external_ids, segments, filters - MMS: media_url - Scheduling: send_after - Sender: sms_from ### Transactional (1 tool) | Tool | Description | API Key | |------|-------------|---------| | `send_transactional_message` | Immediate transactional message | App | ### Message Management (5 tools) | Tool | Description | API Key | |------|-------------|---------| | `view_messages` | List recent messages | App | | `view_message_details` | Get message details | App | | `view_message_history` | View delivery history | App | | `cancel_message` | Cancel scheduled message | App | | `export_audience_activity` | Export engagement CSV | App | ### Segments (3 tools) | Tool | Description | API Key | |------|-------------|---------| | `view_segments` | List all segments | App | | `create_segment` | Create segment with filters | App | | `delete_segment` | Delete segment | App | ### Templates (6 tools) | Tool | Description | API Key | |------|-------------|---------| | `view_templates` | List templates | App | | `view_template_details` | Get template details | App | | `create_template` | Create template | App | | `update_template` | Update template | App | | `delete_template` | Delete template | App | | `copy_template_to_app` | Copy to another app | App | ### Users (7 tools) | Tool | Description | API Key | |------|-------------|---------| | `create_user` | Create user with identity | App | | `view_user` | Get user details | App | | `update_user` | Update user properties | App | | `delete_user` | Delete user | App | | `view_user_identity` | View user aliases | App | | `create_or_update_alias` | Add/update alias | App | | `delete_alias` | Remove alias | App | ### Subscriptions (5 tools) | Tool | Description | API Key | |------|-------------|---------| | `create_subscription` | Add subscription | App | | `update_subscription` | Enable/disable subscription | App | | `delete_subscription` | Remove subscription | App | | `transfer_subscription` | Move to another user | App | | `unsubscribe_email` | Unsubscribe via token | App | ### Live Activities (4 tools) | Tool | Description | API Key | |------|-------------|---------| | `start_live_activity` | Start basic Live Activity | App | | `start_live_activity_advanced` | Start with full options | App | | `update_live_activity` | Update running activity | App | | `end_live_activity` | End activity | App | ### Analytics & Events (3 tools) | Tool | Description | API Key | |------|-------------|---------| | `view_outcomes` | View metrics | App | | `export_messages_csv` | Export message data | Org | | `create_custom_events` | Track custom events | App | ## Implementation Details ### User ID Auto-Detection The server automatically determines if a `user_id` is a OneSignal ID (UUID) or external ID: ```python uuid_pattern = r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' if re.match(uuid_pattern, user_id.lower()): alias_label = "onesignal_id" else: alias_label = "external_id" ``` ### API Key Routing Endpoints are automatically routed to the correct API key: ```python def requires_org_api_key(endpoint: str) -> bool: if endpoint == "apps": return True if re.match(r"^apps/[^/]+$", endpoint): return True if re.match(r"^apps/[^/]+/auth/tokens", endpoint): return True return False ``` ### Error Handling All API errors are caught and returned in a consistent format: ```python {"error": "Error message from OneSignal API"} ``` ### Multi-App Support The server supports multiple OneSignal apps: 1. **Environment Variables**: Set `ONESIGNAL_APP_ID` and `ONESIGNAL_API_KEY` 2. **Dynamic Addition**: Use `add_app` tool to add apps at runtime 3. **Switching**: Use `switch_app` to change current context ## Filter Examples ### Tag-based Targeting ```json [{"field": "tag", "key": "level", "relation": ">", "value": "10"}] ``` ### Location-based Targeting ```json [{"field": "location", "radius": "10000", "lat": "37.7749", "long": "-122.4194"}] ``` ### Multiple Conditions ```json [ {"field": "tag", "key": "plan", "relation": "=", "value": "premium"}, {"operator": "AND"}, {"field": "last_session", "relation": ">", "hours_ago": "24"} ] ``` ## Version History - **2.1.0**: Current release - 50+ tools, multi-app support, all channels - **2.0.0**: Complete rewrite with FastMCP framework - **1.0.0**: Initial release ## Resources - [OneSignal API Reference](https://documentation.onesignal.com/reference) - [Model Context Protocol](https://modelcontextprotocol.io/) - [FastMCP Documentation](https://github.com/modelcontextprotocol/python-sdk)