Onesignal

🚀 OneSignal MCP Server

This project is a tool for managing and operating the OneSignal API. It allows you to send push notifications, emails, and SMS, and provides management functions for devices, segments, and templates.

🚀 Quick Start

Prerequisites

• Python 3.6 or higher
• The following libraries must be installed: python-dotenv and requests
• You must have an OneSignal account and obtain the corresponding API credentials

Installation

Option 1: Clone the repository

git clone https://github.com/your-repository-url.git
cd onesignal-mcp-server
pip install -r requirements.txt

Option 2: Install as a Python package (Coming soon)

pip install onesignal-mcp-server

Configuration

Create a .env file and add the following content:

ONESIGNAL_APP_ID=your_app_id_here
ONESIGNAL_API_KEY=your_api_key_here
# Optional: Set the log level, default is INFO
LOG_LEVEL=DEBUG

Refer to the OneSignal documentation to obtain API credentials.

Running the Server

python -m onesignal_mcp_server.runserver

Basic Usage

Sending Push Notifications

from onesignal_mcp_server import NotificationSender

sender = NotificationSender()
response = sender.send_push_notification(
    title="Hello",
    body="World",
    user_ids=["user1", "user2"]
)
print(response.status_code)  # Print the status code

✨ Features

Multi-App Support

The server supports managing multiple OneSignal applications simultaneously. You can achieve this by adding different application configurations.

Push Notification Management

• Send single or batch push notifications
• Support setting scheduled sending
• View detailed information of sent messages

Device Management

• List all registered devices
• Get detailed information of a specific device

Segment Management

• Create new segments
• Delete existing segments
• View all available segments

Template Management

• Create custom notification or email templates
• View detailed information of existing templates

Logging

The server provides detailed logging functionality. The log output format is as follows:

YYYY-MM-DD HH:MM:SS - onesignal-mcp-server - LEVEL - Message

By default, the logs are output to the console. You can adjust the log level by modifying the logging.basicConfig call.

Testing

The project includes a comprehensive test suite that uses the Python built-in unittest framework and tests the server behavior by mocking external API calls.

Running Tests

python -m unittest discover tests

Test Scope

• Application configuration management
• API request handling and authentication
• Error handling and recovery
• Multi-app support
• Organization-level operations

📚 Documentation

Troubleshooting

Common Issues

No available application configuration

If you encounter the error "No application configuration available", please ensure that:

1. Your .env file is set correctly, or
2. You have added the application configuration using the add_app tool

Incorrect API key

If you encounter an authentication error, please check:

1. Whether your API key is correct
2. Whether you are using the correct key for the operation (REST API key vs. Organization-level API key)
3. Whether the key has the corresponding permissions

Rate limiting

OneSignal has limits on API requests. When encountering rate limits, please:

1. Reduce the request frequency
2. Implement a retry logic with exponential backoff

Getting Help

If you encounter unresolved issues, please refer to the OneSignal API documentation or open an issue in the GitHub repository.

Contribution Guidelines

Contributions to improve the OneSignal MCP Server are welcome! Please refer to CONTRIBUTING.md for detailed guidelines.

License

This project is released under the MIT License. Please refer to the LICENSE file for details.

Acknowledgments

Thank you for your support and contributions to the open-source community.