OneSignal MCP Server Interface

An exhaustive Model Context Protocol (MCP) gateway engineered for seamless interaction with the OneSignal Application Programming Interface. This server furnishes a comprehensive operational facade for controlling push alerts, electronic correspondence, short message service, end-user devices, segmented cohorts, content structures, performance metrics, and ancillary OneSignal functionalities through its documented REST endpoints.

Executive Summary

This MCP gateway delivers expansive programmability across the entire OneSignal REST API Reference, exposing a repertoire of 57 distinct operational tools covering the totality of primary OneSignal capabilities:

🚀 Core Capabilities Map

• Omni-Channel Dispatch: Execute notifications across push channels, electronic mail, SMS, and transactional event triggers.
• Subscriber & Endpoint Stewardship: Full lifecycle management (Create, Read, Update, Delete) for user profiles, associated hardware endpoints, and subscription records.
• Sophisticated Audience Structuring: Define and govern user cohorts utilizing intricate filtering criteria.
• Content Artifact Management: Provision, revise, and steward reusable message compositions (templates).
• Apple Live Activity Support: Complete provisioning for real-time, dynamic iOS Live Activities.
• Performance Analysis & Data Extraction: Access outcome attribution data and generate bulk CSV extracts.
• Multi-Application Abstraction: Seamlessly administer multiple distinct OneSignal application environments.
• Security Credential Administration: Functions for generating, modifying, refreshing, and revoking API authentication tokens.
• Organizational Oversight: Perform management tasks applicable across all hosted applications within the enterprise structure.

Prerequisites

• Runtime Environment: Python version 3.7 or newer is mandatory.
• Dependencies: python-dotenv, requests, and the core mcp framework must be installed.
• Credentials: An active OneSignal account coupled with requisite API access permissions.

Deployment Instructions

Method A: Repository Cloning

bash

Obtain the source repository

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

Resolve required libraries

pip install -r requirements.txt

Method B: Direct Package Installation (Future Availability)

bash pip install onesignal-mcp

Configuration Protocol

1. Establish a .env configuration file in the project root containing your credentials:

# Default application credentials (can be overridden or supplemented via API) ONESIGNAL_APP_ID=your_primary_app_identifier ONESIGNAL_API_KEY=your_primary_rest_api_token

# Organizational access token (for global management tasks) ONESIGNAL_ORG_API_KEY=your_organization_level_auth_token

# Supplementary application profiles ONESIGNAL_MANDIBLE_APP_ID=mandible_app_id ONESIGNAL_MANDIBLE_API_KEY=mandible_api_key

ONESIGNAL_WEIRDBRAINS_APP_ID=weirdbrains_app_id ONESIGNAL_WEIRDBRAINS_API_KEY=weirdbrains_api_key

# Logging verbosity control (DEBUG, INFO, WARNING, ERROR, CRITICAL) LOG_LEVEL=INFO

1. Acquire necessary credentials from the OneSignal dashboard:
2. Application ID: Navigate to Settings -> Keys & IDs -> OneSignal App ID
3. REST API Key: Navigate to Settings -> Keys & IDs -> REST API Key
4. Organization Key: Access Organization Settings -> API Keys section

Execution

Launching the Communication Broker

bash python onesignal_server.py

The server initiates, registers its capabilities with the MCP nexus, and makes the complete set of 57 dispatch and management primitives immediately accessible.

Comprehensive Tool Registry (57 Primitives)

📱 Application Configuration (5 Primitives)

• list_apps - Retrieve listing of all locally defined OneSignal application profiles
• add_app - Introduce a novel OneSignal application configuration into local storage
• update_local_app_config - Modify parameters of an existing locally stored application profile
• remove_app - Purge a local OneSignal application profile record
• switch_app - Set the active application context for subsequent API calls

📨 Message Transmission (8 Primitives)

• send_push_notification - Dispatch a mobile push alert
• send_email - Initiate an email transmission via OneSignal infrastructure
• send_sms - Issue an SMS/MMS communication
• send_transactional_message - Deploy immediate-delivery, event-driven messages
• view_messages - Query records of recently dispatched messages
• view_message_details - Fetch granular data pertaining to a specific transmission record
• view_message_history - Review the distribution log and recipient list for a message
• cancel_message - Terminate a transmission that is currently scheduled for future sending

📱 Device Endpoints (6 Primitives)

• view_devices - List all device endpoints subscribed under the current application
• view_device_details - Obtain comprehensive data for an individual device endpoint
• add_player - Register a new endpoint/device identifier
• edit_player - Modify attributes of an extant endpoint record
• delete_player - Erase an endpoint record from the system
• edit_tags_with_external_user_id - Apply tag updates across all associated devices for a given external user ID

🎯 Audience Cohorts (3 Primitives)

• view_segments - List all defined audience segments
• create_segment - Establish a new, distinct audience segment
• delete_segment - Retire an existing segment definition

📄 Content Artifacts (6 Primitives)

• view_templates - Obtain a directory of all stored content templates
• view_template_details - Retrieve the specific configuration of a content artifact
• create_template - Institute a new reusable content artifact
• update_template - Revise the content or configuration of an existing artifact
• delete_template - Permanently remove a content artifact
• copy_template_to_app - Replicate a template across different application contexts

🏢 Application Management (6 Primitives)

• view_app_details - Query specifics for a locally managed application
• view_apps - List all applications registered under the organization scope
• create_app - Provision a completely new OneSignal application entity
• update_app - Modify the core settings of an existing application
• view_app_api_keys - List existing authentication credentials for an application
• create_app_api_key - Issue a new credential set for application access

🔑 Credential Administration (3 Primitives)

• delete_app_api_key - Invalidate and remove a specific application credential
• update_app_api_key - Revise the permissions or status of an existing credential
• rotate_app_api_key - Generate a replacement credential while disabling the old one

👤 User Entities (6 Primitives)

• create_user - Instantiate a new user entity record
• view_user - Retrieve the profile data for a user entity
• update_user - Modify attributes associated with a user entity
• delete_user - Retire a user entity record
• view_user_identity - Get identity resolution information for a user
• view_user_identity_by_subscription - Resolve user identity based on a specific subscription handle

🏷️ Identity Resolution Mappings (3 Primitives)

• create_or_update_alias - Establish or modify a persistent identifier mapping for a user
• delete_alias - Remove a previously established identity mapping
• create_alias_by_subscription - Link a persistent alias directly via a subscription identifier

📬 Subscription Handles (5 Primitives)

• create_subscription - Register a new endpoint subscription record
• update_subscription - Modify parameters of an existing subscription handle
• delete_subscription - Deactivate and remove a subscription handle
• transfer_subscription - Reassign an existing subscription from one user to another
• unsubscribe_email - Invalidate an email address's ability to receive future communications via token invalidation

🎯 Real-Time Contextual Updates (3 Primitives)

• start_live_activity - Initiate a session for an iOS Live Activity
• update_live_activity - Transmit revised data to an active iOS Live Activity
• end_live_activity - Conclude an active iOS Live Activity session

📊 Telemetry & Export Functions (3 Primitives)

• view_outcomes - Query aggregation data related to conversion events
• export_players_csv - Generate a CSV file containing subscriber endpoint data
• export_messages_csv - Generate a CSV file detailing transmission logs

Practical Application Scenarios

Multi-Channel Communication Examples

python

Dispatching a standard push alert

await send_push_notification( title="Greetings!", message="Your scheduled update is ready.", segments=["Engaged Audience"] )

Sending a promotional email

await send_email( subject="Special Offer Inside", body="Preview text here", email_body="

Click to claim your discount!

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

Issuing a verification SMS

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

Triggering an immediate system event notification

await send_transactional_message( channel="sms", content={"message": "Your appointment is confirmed for 2 PM.", "priority": "high"}, recipients={"include_external_user_ids": ["cust_456"]} )

Entity and Endpoint Administration

python

Registering a new authenticated user

profile = await create_user( name="Alice Example", email="alice@corp.net", external_id="USR_A_404", tags={"subscription_tier": "gold", "onboarded": "true"} )

Registering a mobile device endpoint

device_record = await add_player( device_type=2, # iOS platform identifier identifier="ios_device_auth_token_xyz", language="en-GB", tags={"app_version": "2.1.5"} )

Updating user attributes globally

await edit_tags_with_external_user_id( external_user_id="USR_A_404", tags={"last_login_ts": "2024-07-20T10:00:00Z", "total_orders": "12"} )

Real-Time Activity Management

python

Commencing a dynamic status tracker

await start_live_activity( activity_id="trip_T900", push_token="live_activity_token_abc", subscription_id="sub_id_xyz", activity_attributes={"route_id": "R-900"}, content_state={"status": "preparing_pickup", "time_estimate": "10 minutes"} )

Pushing an update to the tracker

await update_live_activity( activity_id="trip_T900", name="trip_status_update", event="update", content_state={"status": "en_route", "time_estimate": "3 minutes"} )

Data Retrieval and Reporting

python

Fetching recent conversion event metrics

outcomes_data = await view_outcomes( outcome_names=["signup_complete", "tutorial_finish"], outcome_time_range="30d", outcome_platforms=["web", "ios"] )

Generating an audience export file

export_job = await export_players_csv( start_date="2024-06-01T00:00:00Z", end_date="2024-06-30T23:59:59Z", segment_names=["High Value Customers"] )

Quality Assurance

The gateway incorporates an extensive regression and functional test suite. Execution commands for quality validation:

bash

Execute the primary test harness script

python test_onesignal_mcp.py

Or utilize the standard Python unittest discovery mechanism

python -m unittest discover tests

Operational Fault Tolerance

The system is engineered for predictable error reporting: - All service failures yield a uniformly structured output. - Messages are detailed to aid root cause analysis. - Built-in mechanisms offer automatic mitigation for transient network interruptions. - Authentication discrepancies result in explicit, actionable error feedback.

Throughput Constraints

OneSignal imposes governing limits on API utilization: - General ceiling: Ten requests per second (RPS) is the standard threshold. - Batch operations may be subject to stricter limits. - The integrated client library provides advisories for managing these constraints proactively.

Community Engagement

We enthusiastically welcome external contributions! Consult the CONTRIBUTING.md document for detailed contribution protocols and standards.

Licensing Terms

This software artifact is distributed under the terms of the MIT License; refer to the LICENSE file for complete stipulations.

Credits and Acknowledgment

• Gratitude extended to OneSignal for developing the underlying notification infrastructure.
• Appreciation to the broader MCP ecosystem for establishing the Model Context Protocol specification.
• Recognition for all developers who have contributed code or documentation to this repository.

WIKIPEDIA_CONTEXT: Business administration platforms encompass methodologies, applications, control mechanisms, computational structures, and conceptual frameworks deployed by enterprises to effectively navigate dynamic market conditions, secure a superior competitive standing, and elevate overall operational efficacy. These solutions span departments, addressing functions such as strategic forecasting, workflow refinement, data archival, personnel administration, strategic selection, performance benchmarking, and knowledge capture. Contemporary business technology has undergone dramatic shifts due to rapid technological acceleration, making discerning the optimal set of tools for any organizational context increasingly complex. This complexity is driven by constant pressures to minimize expenditure, maximize revenue realization, achieve profound comprehension of consumer demands, and deliver products meeting those demands precisely as specified. In this environment, leadership must adopt a forward-looking stance toward technology adoption, favoring thoughtful integration and customization of selected tools over indiscriminate adoption of novel releases. Selection must be judicious, followed by tailoring the platform to intrinsic organizational requirements, rather than forcing the organization to conform to the software's inherent structure.