一信号-MCP
项目介绍
OneSignal MCP Server
一个全面的模型上下文协议（MCP）服务器，用于与OneSignal API交互。此服务器通过OneSignal的REST API提供了一个完整的接口，用于管理推送通知、电子邮件、短信、用户、设备、分段、模板、分析等。
概述
此MCP服务器提供了对OneSignal REST API的全面访问，提供了涵盖所有主要OneSignal操作的57个工具：
🚀 主要功能
- 多渠道消息传递：发送推送通知、电子邮件、短信和事务性消息
- 用户及设备管理：完成用户的创建、读取、更新和删除（CRUD）操作，以及设备和订阅
- 高级分段：使用复杂过滤器创建和管理用户分段
- 模板系统：创建、更新和管理消息模板
- iOS实时活动：完全支持iOS实时活动
- 分析与导出：查看结果数据并导出到CSV
- 多应用支持：无缝管理多个OneSignal应用
- API密钥管理：创建、更新、轮换和删除API密钥
- 组织级操作：跨整个组织管理应用
要求
- Python 3.7或更高版本
python-dotenv包requests包mcp包- 带有API凭证的OneSignal账户
安装
方案1：从GitHub克隆
# 克隆仓库
git clone https://github.com/weirdbrains/onesignal-mcp.git
cd onesignal-mcp
# 安装依赖
pip install -r requirements.txt
方案2：作为包安装（即将推出）
pip install onesignal-mcp
配置
-
在根目录下创建一个
.env文件，并添加您的OneSignal凭证：# 默认应用凭证（可选，您也可以通过API添加应用） ONESIGNAL_APP_ID=your_app_id_here ONESIGNAL_API_KEY=your_rest_api_key_here # 组织API密钥（用于组织级操作） ONESIGNAL_ORG_API_KEY=your_organization_api_key_here # 可选：多个应用配置 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 # 日志级别（DEBUG, INFO, WARNING, ERROR, CRITICAL） LOG_LEVEL=INFO -
查找您的OneSignal凭证：
- 应用ID：设置 > 密钥与ID > OneSignal应用ID
- REST API密钥：设置 > 密钥与ID > REST API密钥
- 组织API密钥：组织设置 > API密钥
使用
运行服务器
python onesignal_server.py
服务器将启动并注册到MCP系统中，使所有57个工具可用。
完整工具参考（57个工具）
📱 应用管理（5个工具）
list_apps- 列出所有已配置的OneSignal应用add_app- 添加一个新的本地OneSignal应用配置update_local_app_config- 更新现有的本地应用配置remove_app- 移除本地OneSignal应用配置switch_app- 切换当前使用的应用进行API请求
📨 消息传递（8个工具）
send_push_notification- 发送推送通知send_email- 通过OneSignal发送电子邮件send_sms- 通过OneSignal发送SMS/MMSsend_transactional_message- 发送即时交付的消息view_messages- 查看最近发送的消息view_message_details- 获取消息的详细信息view_message_history- 查看消息历史/接收者cancel_message- 取消预定的消息
📱 设备/玩家（6个工具）
view_devices- 查看订阅了您应用的设备view_device_details- 获取设备的详细信息add_player- 添加新的玩家/设备edit_player- 编辑现有的玩家/设备delete_player- 删除玩家/设备记录edit_tags_with_external_user_id- 批量编辑外部ID的标签
🎯 分段（3个工具）
view_segments- 列出所有分段create_segment- 创建新的分段delete_segment- 删除分段
📄 模板（6个工具）
view_templates- 列出所有模板view_template_details- 获取模板详情create_template- 创建新的模板update_template- 更新现有模板delete_template- 删除模板copy_template_to_app- 将模板复制到另一个应用
🏢 应用（6个工具）
view_app_details- 获取已配置应用的详细信息view_apps- 列出所有组织应用create_app- 创建新的OneSignal应用update_app- 更新现有应用view_app_api_keys- 查看应用的API密钥create_app_api_key- 创建新的API密钥
🔑 API密钥管理（3个工具）
delete_app_api_key- 删除API密钥update_app_api_key- 更新API密钥rotate_app_api_key- 轮换API密钥
👤 用户（6个工具）
create_user- 创建新用户view_user- 查看用户详细信息update_user- 更新用户信息delete_user- 删除用户view_user_identity- 获取用户身份信息view_user_identity_by_subscription- 根据订阅获取身份
🏷️ 别名（3个工具）
create_or_update_alias- 创建或更新用户别名delete_alias- 删除用户别名create_alias_by_subscription- 根据订阅ID创建别名
📬 订阅（5个工具）
create_subscription- 创建新的订阅update_subscription- 更新订阅delete_subscription- 删除订阅transfer_subscription- 在用户之间转移订阅unsubscribe_email- 使用电子邮件令牌取消订阅
🎯 实时活动（3个工具）
start_live_activity- 开始iOS实时活动update_live_activity- 更新iOS实时活动end_live_activity- 结束iOS实时活动
📊 分析与导出（3个工具）
view_outcomes- 查看结果/转化数据export_players_csv- 将玩家数据导出到CSVexport_messages_csv- 将消息导出到CSV
使用示例
多渠道消息传递
# 发送推送通知
await send_push_notification(
title="Hello World",
message="这是一条测试通知",
segments=["订阅用户"]
)
# 发送电子邮件
await send_email(
subject="欢迎！",
body="感谢加入我们",
email_body="<html><body><h1>欢迎！</h1></body></html>",
include_emails=["user@example.com"]
)
# 发送短信
await send_sms(
message="您的验证码是12345",
phone_numbers=["+15551234567"]
)
# 发送事务性消息
await send_transactional_message(
channel="email",
content={"subject": "订单确认", "body": "您的订单已被确认"},
recipients={"include_external_user_ids": ["user123"]}
)
用户和设备管理
# 创建用户
user = await create_user(
name="John Doe",
email="john@example.com",
external_id="user123",
tags={"计划": "高级", "加入日期": "2024-01-01"}
)
# 添加设备
device = await add_player(
device_type=1, # Android
identifier="设备令牌",
language="en",
tags={"应用版本": "1.0.0"}
)
# 更新用户标签
await edit_tags_with_external_user_id(
external_user_id="user123",
tags={"最后活跃": "2024-01-15", "购买次数": "5"}
)
iOS实时活动
# 开始实时活动
await start_live_activity(
activity_id="delivery_123",
push_token="实时活动推送令牌",
subscription_id="用户订阅ID",
activity_attributes={"订单号": "12345"},
content_state={"状态": "准备中", "预计到达时间": "15分钟"}
)
# 更新实时活动
await update_live_activity(
activity_id="delivery_123",
name="delivery_update",
event="更新",
content_state={"状态": "正在路上", "预计到达时间": "5分钟"}
)
分析与导出
# 查看转化结果
outcomes = await view_outcomes(
outcome_names=["购买", "会话时长"],
outcome_time_range="7d",
outcome_platforms=["ios", "android"]
)
# 导出玩家数据
export = await export_players_csv(
start_date="2024-01-01T00:00:00Z",
end_date="2024-01-31T23:59:59Z",
segment_names=["活跃用户"]
)
测试
服务器包含一个全面的测试套件。运行测试：
# 运行测试脚本
python test_onesignal_mcp.py
# 或使用unittest
python -m unittest discover tests
错误处理
服务器提供一致的错误处理：
- 所有错误都以标准化格式返回
- 详细的错误消息有助于识别问题
- 对于瞬时故障的自动重试逻辑
- 正确的认证错误消息
速率限制
OneSignal对API请求实施速率限制：
- 标准限制：每秒10次请求
- 批量操作：可能有更低的限制
- 服务器包括关于如何处理速率限制的指导
贡献
我们欢迎贡献！请参阅CONTRIBUTING.md了解指南。
许可证
本项目根据MIT许可证发布 - 详情见LICENSE文件。
致谢
- OneSignal 提供了出色的推送服务
- MCP社区提供了模型上下文协议
- 所有对此项目的贡献者