OneSignal MCP 服务器

用于与 OneSignal API 交互的模型上下文协议 (MCP) 服务器。该服务器提供了一个便捷的界面，可通过 OneSignal 的 REST API 管理推送通知、电子邮件、短信、用户设备、细分、模板等。

概述

此 MCP 服务器封装了OneSignal REST API ，提供了一套用于管理 OneSignal 应用程序和向用户发送消息的工具。它支持所有主要的 OneSignal 操作，包括：

发送推送通知、电子邮件和短信
管理用户设备和订阅
创建和管理细分
创建和管理模板
查看应用程序信息和分析
组织级操作
管理多个 OneSignal 应用程序

要求

Python 3.7 或更高版本
python-dotenv包
requests包
具有 API 凭证的 OneSignal 帐户

安装

选项 1：从 GitHub 克隆

# Clone the repository
git clone https://github.com/weirdbrains/onesignal-mcp.git
cd onesignal-mcp

# Install dependencies
pip install -r requirements.txt

选项 2：作为软件包安装（即将推出）

pip install onesignal-mcp

配置

使用您的 OneSignal 凭证在根目录中创建一个.env文件：
# Default app credentials (optional, you can also add apps via the API) ONESIGNAL_APP_ID=your_app_id_here ONESIGNAL_API_KEY=your_rest_api_key_here # Organization API key (for org-level operations) ONESIGNAL_ORG_API_KEY=your_organization_api_key_here
您可以在 OneSignal 仪表板中找到您的 OneSignal 凭证：
- 应用程序 ID：设置 > 密钥和 ID > OneSignal 应用程序 ID
- REST API 密钥：设置 > 密钥和 ID > REST API 密钥
- 组织 API 密钥：组织设置 > API 密钥

用法

运行服务器

python onesignal_server.py

服务器将启动并在 MCP 系统中注册，使其工具可供使用。

基本用法示例

发送推送通知

# Send a notification to all subscribed users
result = await send_notification(
    title="Hello World",
    message="This is a test notification",
    segment="Subscribed Users"
)
print(result)

使用多个应用程序

# Add a new app configuration
await add_app(
    key="my_second_app", 
    app_id="second-app-id", 
    api_key="second-app-api-key", 
    name="My Second App"
)

# List all configured apps
apps = await list_apps()
print(apps)

# Switch to the new app
await switch_app("my_second_app")

# Send a notification using the current app
await send_notification(
    title="Hello", 
    message="This is from my second app"
)

# Send a notification from a specific app (without switching)
await send_notification(
    title="Hello", 
    message="This is from my first app", 
    app_key="mandible"
)

管理细分

# List all segments
segments = await view_segments()
print(segments)

# Create a new segment
result = await create_segment(
    name="High Value Users",
    filters='[{"field":"amount_spent", "relation":">", "value":"100"}]'
)
print(result)

使用模板

# Create an email template
result = await create_template(
    name="Welcome Email",
    title="Welcome to Our App",
    message="<html><body><h1>Welcome!</h1><p>Thank you for joining us.</p></body></html>",
    template_type="email"
)
print(result)

多应用支持

此服务器支持管理多个 OneSignal 应用程序。您可以：

添加具有不同标识符的多个应用配置
进行 API 调用时在应用程序之间切换
指定要用于单个操作的应用程序

应用程序管理工具

list_apps ：列出服务器中所有已配置的 OneSignal 应用
add_app ：添加新的 OneSignal 应用配置
update_app ：更新现有的 OneSignal 应用配置
remove_app ：删除 OneSignal 应用配置
switch_app ：切换当前应用程序以用于 API 请求

可用工具

消息管理

send_notification ：发送新的推送通知、电子邮件或短信
view_messages ：列出通过 OneSignal 发送的最近消息
view_message_details ：获取有关特定消息的详细信息
cancel_message ：取消预定的消息

设备管理

view_devices ：列出您的 OneSignal 应用中注册的设备（用户）
view_device_details ：获取特定设备的详细信息

段管理

view_segments ：列出 OneSignal 应用中可用的所有段
create_segment ：使用指定的过滤器创建一个新的段
delete_segment ：删除现有段

模板管理

view_templates ：列出 OneSignal 应用中可用的所有模板
view_template_details ：获取有关特定模板的详细信息
create_template ：为通知或电子邮件创建新模板

应用信息

view_app_details ：获取有关已配置的 OneSignal 应用的详细信息

日志记录

该服务器包含全面的日志记录，可帮助进行调试和监控。日志默认输出到控制台，格式如下：

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

您可以通过修改服务器文件中的logging.basicConfig调用来调整日志记录级别。

测试

OneSignal MCP 服务器包含一套全面的测试套件，以确保所有功能均按预期运行。这些测试使用 Python 内置的unittest框架并模拟外部 API 调用来测试服务器的行为。

运行测试

要运行测试，请使用以下命令：

python -m unittest discover tests

这将发现并运行tests目录中的所有测试。

测试覆盖率

测试套件涵盖：

应用程序配置管理
使用适当的身份验证来处理 API 请求
错误处理和恢复
多应用程序支持
组织级操作

编写新测试

如果您向服务器添加新功能，请同时添加相应的测试。测试应放在tests目录中，并遵循命名约定test_*.py 。

故障排除

常见问题

没有可用的应用程序配置

如果您看到错误“没有可用的应用程序配置”，请确保您已：

使用正确的凭据设置.env文件，或者
使用add_app工具添加了应用程序配置

API 密钥错误

如果收到身份验证错误，请验证：

您的 API 密钥正确
您正在使用正确的密钥进行操作（REST API 密钥与组织 API 密钥）
该密钥具有 OneSignal 中的必要权限

速率限制

OneSignal 对 API 请求设有速率限制。如果您遇到速率限制：

减少请求的频率
使用指数退避算法实现重试逻辑

获取帮助

如果您遇到此处未涵盖的问题：

查看OneSignal API 文档
在 GitHub 存储库上打开一个问题

贡献

欢迎大家为改进 OneSignal MCP 服务器做出贡献！请参阅CONTRIBUTING.md中的指南。

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。

致谢

OneSignal提供出色的通知服务和 API
Weirdbrains 团队对该项目的支持

OneSignal MCP Server

Integrations