OneSignal Unified Communication Fabric (MCP)

This Model Context Protocol (MCP) server acts as a centralized control plane for engaging with the entire OneSignal ecosystem via its comprehensive RESTful interface. It encapsulates all necessary complexities for orchestrating push notifications, electronic mail delivery, SMS dissemination, subscriber entity administration, cohort definition, and content asset management.

Conceptual Summary

This abstraction fabric exposes 57 distinct capabilities (tools), granting granular control over all core functionalities exposed by the underlying OneSignal REST API documentation.

✨ Core Operational Capabilities

• Omni-Channel Dispatch: Execution of communications across mobile push, transactional email, standard SMS, and on-demand messages.
• Identity & Endpoint Administration: Full spectrum CRUD operations for managing user profiles, device endpoints, and subscription status.
• Audience Sculpting: Mechanisms to formulate and maintain sophisticated user subsets using complex filtering criteria.
• Content Artifacts: Lifecycle management (creation, modification, deletion) of reusable message blueprints (templates).
• Platform Specific Support: Full integration for managing real-time state updates via iOS Live Activities.
• Performance Metrics: Access to conversion outcomes and bulk data extraction (CSV format).
• Multi-Application Orchestration: Seamless handling and switching between multiple distinct OneSignal application contexts.
• Security Credential Handling: Tools for generating, refreshing, decommissioning, and modifying application API access tokens.
• Organizational Scope Control: Capabilities to administer resources and settings across the entire corporate OneSignal tenancy.

Prerequisites

• Execution environment requires Python version 3.7 or newer.
• Dependencies include: python-dotenv, requests, and the core mcp framework library.
• Valid OneSignal API access credentials are mandatory.

Deployment Procedure

Method A: Source Repository Checkout

bash

Obtain the source code

git clone https://github.com/weirdbrains/onesignal-mcp.git cd onesignal-mcp

Install requisite libraries

pip install -r requirements.txt

Method B: Direct Package Installation (Future Release)

bash pip install onesignal-mcp

Configuration Setup

Populate a .env file in the root directory with necessary access secrets:

dotenv

Primary application credentials (can be overridden by tool calls)

ONESIGNAL_APP_ID=your_primary_app_identifier ONESIGNAL_API_KEY=your_primary_rest_secret

Credentials for tenancy-wide operations

ONESIGNAL_ORG_API_KEY=your_organization_access_token

Example configurations for secondary applications

ONESIGNAL_MANDIBLE_APP_ID=secondary_app_id_1 ONESIGNAL_MANDIBLE_API_KEY=secondary_api_key_1

Runtime verbosity setting (e.g., DEBUG, INFO, WARNING)

LOG_LEVEL=INFO

Credential sourcing guide: - Application Identifier: OneSignal Dashboard > Settings > Keys & IDs > App ID. - REST Secret: OneSignal Dashboard > Settings > Keys & IDs > REST API Key. - Organization Token: Organization Settings > API Keys Management.

Execution

To activate the control plane:

bash python onesignal_server.py

The server initializes and registers all 57 available functions within the MCP registry for external invocation.

Full Tool Catalog (57 Capabilities)

📱 Application Context Administration (5 functions)

• list_apps - Retrieve all locally configured OneSignal application metadata.
• add_app - Integrate a new application configuration into the local context store.
• update_local_app_config - Modify existing parameters for a locally stored application configuration.
• remove_app - Purge an application configuration from the local store.
• switch_app - Designate the active application context for subsequent API interactions.

📨 Message Dispatch Operations (8 functions)

• send_push_notification - Initiate a mobile push broadcast/direct message.
• send_email - Trigger an email communication via the OneSignal service.
• send_sms - Dispatch an SMS or MMS message.
• send_transactional_message - Deliver immediate, non-scheduled transactional alerts.
• view_messages - Fetch a log of recently transmitted messages.
• view_message_details - Acquire granular status reports for a specific message ID.
• view_message_history - Examine the recipient list and delivery progression for a broadcast.
• cancel_message - Invalidate a message that is currently pending scheduled delivery.

📱 Device/Endpoint Management (6 functions)

• view_devices - Query the registry of subscribed endpoints for the active application.
• view_device_details - Retrieve comprehensive data for a singular device identifier.
• add_player - Register a new mobile endpoint/player record.
• edit_player - Modify attributes associated with an existing device record.
• delete_player - Decommission an endpoint record from the system.
• edit_tags_with_external_user_id - Perform batch modification of attribute tags linked to a specific external user ID.

🎯 Audience Definition (3 functions)

• view_segments - Enumerate all defined audience segments.
• create_segment - Establish a novel user segment definition.
• delete_segment - Retire an existing segment definition.

📄 Content Blueprinting (6 functions)

• view_templates - List all stored communication templates.
• view_template_details - Fetch the specific payload and configuration of a template.
• create_template - Author and save a new content template.
• update_template - Revise the content or metadata of an existing template.
• delete_template - Erase a saved content template.
• copy_template_to_app - Replicate a template structure across different managed applications.

🏢 Organization Application Control (6 functions)

• view_app_details - Obtain the current manifest for an application context.
• view_apps - List all applications registered under the organization scope.
• create_app - Provision a completely new OneSignal application entity.
• update_app - Modify the fundamental properties of an existing application.
• view_app_api_keys - List all associated credentials for a specific application.
• create_app_api_key - Issue a new secret key for application-level access.

🔑 Credential Security Management (3 functions)

• delete_app_api_key - Invalidate and remove a specific API access credential.
• update_app_api_key - Modify permissions or metadata for an existing key.
• rotate_app_api_key - Generate a new secret while simultaneously retiring the old one.

👤 User Identity Records (6 functions)

• create_user - Provision a new abstract user identity record.
• view_user - Query the details associated with a user identity.
• update_user - Modify user profile attributes.
• delete_user - Remove a user identity from the system.
• view_user_identity - Resolve the primary identity mappings for a user.
• view_user_identity_by_subscription - Map a specific subscription ID back to its owning user record.

🏷️ Identity Linkages (3 functions)

• create_or_update_alias - Establish or modify the linkage between an external ID and a user record.
• delete_alias - Remove an established identity alias.
• create_alias_by_subscription - Link an alias directly via a subscription reference.

📬 Subscription Objects (5 functions)

• create_subscription - Register a new channel subscription object.
• update_subscription - Modify attributes of an existing subscription record.
• delete_subscription - Decommission a subscription object.
• transfer_subscription - Reassign a subscription from one user entity to another.
• unsubscribe_email - Revoke email privileges using an associated token.

🎯 Real-Time Activity Tracking (3 functions)

• start_live_activity - Initiate a new dynamic context session (iOS).
• update_live_activity - Push data modifications to an active session.
• end_live_activity - Terminate an active session cleanly.

📊 Performance Data Extraction (3 functions)

• view_outcomes - Fetch aggregated conversion event statistics.
• export_players_csv - Generate a CSV dump of endpoint data within a time frame.
• export_messages_csv - Generate a CSV report detailing message transmission logs.

Operational Demonstrations

Multi-Channel Communication Examples

python

Push message dispatch

await send_push_notification( title="Greetings", message="System notification test", segments=["Engaged Audience"] )

Email dispatch

await send_email( subject="Welcome Aboard", body="Text content", email_body="

Welcome!

", include_emails=["client@domain.com"] )

SMS dispatch

await send_sms( message="Verify code: 9876", phone_numbers=["+19998887777"] )

Transactional payload

await send_transactional_message( channel="sms", content={"body": "Your transaction reference is TXN-456"}, recipients={"include_external_user_ids": ["cust_007"]} )

Identity and Device Lifecycle

python

User record creation

user_record = await create_user( name="Alice Example", email="alice@test.com", external_id="user_abc_99", tags={"tier": "gold", "region": "NA"} )

New device registration

device_record = await add_player( device_type=2, # iOS indicator identifier="ios_device_token_xyz", language="en-US", tags={"os_version": "17.1"} )

Mass tag update for a user

await edit_tags_with_external_user_id( external_user_id="user_abc_99", tags={"last_seen": "2024-11-20", "active_session": "true"} )

Integrity Validation

The integrated verification suite ensures component reliability.

bash

Execute the full test suite runner

python test_onesignal_mcp.py

Alternatively, use Python's standard unittest discovery

python -m unittest discover tests

Reliability and Support

This module ensures standardized handling for operational anomalies: - Error Standardization: All failures conform to a uniform output schema. - Diagnostic Detail: Messages are structured to pinpoint the source of the exception. - Transient Failure Mitigation: Built-in logic for automatically retrying temporary network interruptions. - Authentication Feedback: Clear reporting when credentialing issues arise.

Quota Management

Adherence to OneSignal API rate constraints is critical: - Default Throttling: Generally set to 10 operations per second. - Bulk Limits: Higher volume operations may face stricter caps. - Guidance: The system provides context for constructing requests that respect these limits.

Contribution Guidelines

We encourage community participation. Refer to CONTRIBUTING.md for submission specifications.

Licensing

This codebase is distributed under the permissive MIT License (see LICENSE).

Recognition

• Gratitude to OneSignal for providing a foundational messaging platform.
• Appreciation for the architecture established by the Model Context Protocol community.
• Acknowledgment to all developers who have contributed code and feedback.

WIKIPEDIA CONTEXT RELEVANCE: Elasticity, a core attribute of cloud resources as defined by NIST (National Institute of Standards and Technology), directly relates to the ability of this MCP server to rapidly scale the number of active processes or data throughput needed to handle high-volume messaging events without service degradation, mirroring the 'Rapid elasticity' characteristic.