OneSignal MCP Server

OneSignal MCP 服务

一款功能全面的模型上下文协议（MCP）服务，可用于与 OneSignal API 交互。此服务通过 OneSignal 的 REST API，提供完整的接口，用于管理推送通知、电子邮件、短信、用户、设备、细分、模板、分析等。

概览

此 MCP 服务提供对 OneSignal REST API 的全面访问，提供 57 个工具，涵盖 OneSignal 的所有主要操作：

🚀 主要功能

• 多渠道消息传递：发送推送通知、电子邮件、短信和事务性消息
• 用户与设备管理：对用户、设备和订阅执行完整的 CRUD 操作
• 高级细分：使用复杂筛选条件创建和管理用户细分
• 模板系统：创建、更新和管理消息模板
• iOS 实时活动：全面支持 iOS 实时活动
• 分析与导出：查看效果数据并导出为 CSV
• 多应用支持：无缝管理多个 OneSignal 应用
• API 密钥管理：创建、更新、轮换和删除 API 密钥
• 组织级操作：管理整个组织中的应用

要求

• Python 3.7 或更高版本
• python-dotenv 包
• requests 包
• mcp 包
• 拥有 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

配置

1. 在根目录中创建 .env 文件，并填入 OneSignal 凭据：

   # 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
   
   # Optional: Multiple app configurations
   ONESIGNAL_AIBOOKCRAFT_APP_ID=aibookcraft_app_id
   ONESIGNAL_AIBOOKCRAFT_API_KEY=aibookcraft_api_key
   
   ONESIGNAL_WEIRDBRAINS_APP_ID=weirdbrains_app_id
   ONESIGNAL_WEIRDBRAINS_API_KEY=weirdbrains_api_key
   
   # Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
   LOG_LEVEL=INFO
   

2. 查找 OneSignal 凭据：

   • App ID：Settings > Keys & IDs > OneSignal App ID
   • REST API Key：Settings > Keys & IDs > REST API Key
   • Organization API Key：Organization Settings > API Keys

使用方法

运行服务

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/MMS
• send_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 - 将玩家数据导出为 CSV
• export_messages_csv - 将消息导出为 CSV

使用示例

多渠道消息传递

# Send a push notification
await send_push_notification(
    title="Hello World",
    message="This is a test notification",
    segments=["Subscribed Users"]
)

# Send an email
await send_email(
    subject="Welcome!",
    body="Thank you for joining us",
    email_body="<html><body><h1>Welcome!</h1></body></html>",
    include_emails=["[email protected]"]
)

# Send an SMS
await send_sms(
    message="Your verification code is 12345",
    phone_numbers=["+15551234567"]
)

# Send a transactional message
await send_transactional_message(
    channel="email",
    content={"subject": "Order Confirmation", "body": "Your order has been confirmed"},
    recipients={"include_external_user_ids": ["user123"]}
)

用户和设备管理

# Create a user
user = await create_user(
    name="John Doe",
    email="[email protected]",
    external_id="user123",
    tags={"plan": "premium", "joined": "2024-01-01"}
)

# Add a device
device = await add_player(
    device_type=1,  # Android
    identifier="device_token_here",
    language="en",
    tags={"app_version": "1.0.0"}
)

# Update user tags across all devices
await edit_tags_with_external_user_id(
    external_user_id="user123",
    tags={"last_active": "2024-01-15", "purchases": "5"}
)

iOS 实时活动

# Start a Live Activity
await start_live_activity(
    activity_id="delivery_123",
    push_token="live_activity_push_token",
    subscription_id="user_subscription_id",
    activity_attributes={"order_number": "12345"},
    content_state={"status": "preparing", "eta": "15 mins"}
)

# Update the Live Activity
await update_live_activity(
    activity_id="delivery_123",
    name="delivery_update",
    event="update",
    content_state={"status": "on_the_way", "eta": "5 mins"}
)

分析与导出

# View conversion outcomes
outcomes = await view_outcomes(
    outcome_names=["purchase", "session_duration"],
    outcome_time_range="7d",
    outcome_platforms=["ios", "android"]
)

# Export player data
export = await export_players_csv(
    start_date="2024-01-01T00:00:00Z",
    end_date="2024-01-31T23:59:59Z",
    segment_names=["Active Users"]
)

测试

该服务包含全面的测试套件。运行测试：

# Run the test script
python test_onesignal_mcp.py

# Or use unittest
python -m unittest discover tests

错误处理

该服务提供一致的错误处理：

• 所有错误均以标准化格式返回
• 详细的错误消息有助于识别问题
• 针对临时故障的自动重试逻辑
• 清晰的身份验证错误消息

速率限制

OneSignal 对 API 请求实施速率限制：

• 标准限制：每秒 10 个请求
• 批量操作：限制可能更低
• 该服务提供了处理速率限制的指导

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• 感谢 OneSignal 提供出色的通知服务
• 感谢 MCP 社区对 Model Context Protocol 的支持
• 感谢本项目的所有贡献者