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

This OneSignal MCP Server enables you to efficiently manage and operate the OneSignal API, facilitating the sending of push notifications, emails, and SMS, along with device, segment, and template management.

✨ Features

Push Notification Management

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

Device Management

• List all registered devices.
• Get detailed information of specific devices.

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.

Multi - App Support

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

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, logs are output to the console. You can adjust the log level by modifying the logging.basicConfig call.

📦 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

💻 Usage Examples

Basic Usage

Run the Server

python -m onesignal_mcp_server.runserver

Send a Push Notification

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

📚 Documentation

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.

Testing

The project includes a comprehensive test suite using the Python built - in unittest framework and simulates external API calls to test server behavior.

Run 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

Troubleshooting

Common Issues

No Available App Configuration

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

1. Your .env file is set up correctly, or
2. You have added app configurations using the add_app tool.

API Key Error

If you encounter an authentication error, 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.

Get Help

If you encounter unresolved issues, 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.