> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OneSignal MCP 服务器

> 使用托管的 MCP 服务器 URL，将任何支持远程 MCP 服务器的 AI 工具或代理连接到 OneSignal。涵盖在 Claude Code、Codex CLI、Cursor、VS Code 和自定义连接器中的设置，以及服务器支持的所有工具，包括 Journey 工具。

添加 OneSignal MCP 服务器 URL，即可将 OneSignal 连接到任何支持远程 Model Context Protocol (MCP) 服务器的 AI 工具或代理。使用本页面连接 Cursor、Claude Code、Codex CLI、VS Code 或您自己的代理，或查看完整的工具列表。要从 Claude 或 ChatGPT 目录安装 OneSignal，请参阅[在 Claude 和 ChatGPT 中使用 OneSignal](https://documentation.onesignal.com/docs/en/onesignal-in-claude-chatgpt.md)。

[MCP](https://modelcontextprotocol.io/docs/getting-started/intro) 是一种将 AI 应用连接到外部系统的开放标准。OneSignal MCP 服务器将 OneSignal 操作（例如查找用户或发送消息）作为您的 AI 工具可以调用的工具公开。

## 前提条件 \\

* 一个可以访问您要管理的 OneSignal 应用的 OneSignal 账户。
* 通过 OAuth（OneSignal 使用的基于浏览器的登录方式）批准 OneSignal 访问的权限。
* 一个支持通过 HTTP 和 OAuth 连接远程 MCP 服务器的 AI 工具。

## 连接详情 \\

每个 AI 工具都连接到同一个托管端点：

```text theme={null}
https://api.onesignal.com/mcp/oauth
```

您需要在浏览器中登录 OneSignal 并批准访问来完成身份验证。无需配置 REST API 密钥。请将所有 OAuth 客户端 ID 和客户端密钥字段留空：OneSignal 会自动注册您的 AI 工具，填写这些值会导致连接失败。

## 设置您的 AI 工具 \\

### Cursor \\

从 Cursor Marketplace 安装 OneSignal。

**1. 打开 OneSignal 插件**

前往 [Cursor Marketplace 中的 OneSignal](https://cursor.com/marketplace/onesignal)，或在 Cursor 的 Marketplace 中搜索 **OneSignal**。

**2. 安装插件**

点击 **Add to Cursor**。Cursor 会安装 OneSignal 插件，其中包括 MCP 服务器。

**3. 登录 OneSignal**

打开 **Settings > MCP & Integrations**，然后点击 OneSignal 旁边的 **Authenticate**。在浏览器中登录并点击 **Agree & Allow Access**。

**4. 在 Agent 聊天中使用 OneSignal**

开始一个新的 Agent 聊天，并让 OneSignal 执行只读检查，例如列出您的 OneSignal 应用。

如果要手动配置 Cursor，请将 OneSignal 添加到您的 `mcp.json`：

```json theme={null}
{
  "mcpServers": {
    "onesignal": {
      "url": "https://api.onesignal.com/mcp/oauth"
    }
  }
}
```

### Claude Code \\

**1. 添加 OneSignal MCP 服务器**

在终端中运行以下命令：

```bash theme={null}
claude mcp add --transport http onesignal https://api.onesignal.com/mcp/oauth
```

**2. 在 Claude Code 中进行身份验证**

启动 `claude`，然后输入 `/mcp` 打开 MCP 面板。选择 **onesignal**，然后选择 **Authenticate**，在浏览器中打开 OneSignal 登录页面。

**3. 批准访问**

登录并点击 **Agree & Allow Access**。返回 Claude Code。服务器状态会变为 **connected**。

运行 `claude mcp list`，或在 Claude Code 中运行 `/mcp`，即可查看工具数量。

### Claude 自定义连接器 \\

仅当您无法从 [Claude 目录](https://claude.ai/directory/connectors/onesignal)安装 OneSignal 时，才使用自定义连接器。远程 MCP 服务器无法通过 `claude_desktop_config.json` 添加，该文件仅用于本地 `stdio` 服务器。

**1. 添加自定义连接器**

前往 **Customize > Connectors** 并点击 **Add custom connector**。

**2. 输入服务器详情**

将 **Name** 设置为 `OneSignal`，将 **Remote MCP server URL** 设置为 `https://api.onesignal.com/mcp/oauth`。将 **Advanced settings** 下的 **OAuth Client ID** 和 **OAuth Client Secret** 留空。

**3. 登录 OneSignal**

点击 **Add**，然后在浏览器中完成 OneSignal 登录并点击 **Agree & Allow Access**。

### Codex CLI \\

**1. 打开插件浏览器**

运行 `codex`，然后输入 `/plugins`。

**2. 安装 OneSignal**

找到 **OneSignal**，打开并安装它。

**3. 开始新会话并登录**

开始一个新会话。当 Codex 要求您进行身份验证时，在浏览器中登录 OneSignal 并点击 **Agree & Allow Access**。

Codex IDE 扩展不支持插件。要在 Codex 中使用 OneSignal，请从 Codex CLI 或 ChatGPT 桌面应用的 **Plugins** 标签页安装。

### VS Code 中的 GitHub Copilot \\

将 OneSignal 添加到工作区的 `.vscode/mcp.json` 中以与团队共享，或从命令面板运行 **MCP: Open User Configuration** 为您的用户配置文件安装：

```json theme={null}
{
  "servers": {
    "onesignal": {
      "type": "http",
      "url": "https://api.onesignal.com/mcp/oauth"
    }
  }
}
```

Copilot 第一次需要使用 OneSignal 工具时，VS Code 会提示您进行身份验证并打开 OneSignal 登录页面。

### 其他 AI 工具和代理 \\

在您的 AI 工具的远程 MCP 服务器设置中添加 `https://api.onesignal.com/mcp/oauth`。AI 工具第一次调用 OneSignal 工具时，会在浏览器中打开 OneSignal 登录页面。登录并点击 **Agree & Allow Access**。连接成功后，您的 AI 工具会列出 OneSignal 工具。

## 验证连接 \\

开始一个新的聊天或会话并发送：

```text theme={null}
Use the list_apps tool to list the OneSignal apps I can access.
```

如果响应列出了您的 OneSignal 应用，则连接正常。如果返回 "tool access is not enabled for this application"，请参阅[故障排除](#troubleshooting)。

如果只想检查您的 AI 工具能否访问服务器，请调用 `onesignal_health`。它在 AI 工具访问权限开启之前就会响应，因此健康的结果并不能确认其他工具可以正常工作。

## 故障排除 \\

* **重新进行身份验证。** 从您的 AI 工具的 MCP 或连接器设置中重新连接 OneSignal，然后开始新会话。

* **检查服务器 URL。** URL 必须完全为 `https://api.onesignal.com/mcp/oauth`，不能有额外的路径或尾随字符。

* **清空 OAuth 客户端字段。** 如果您的 AI 工具有 OAuth 客户端 ID 或密钥字段，请将其留空。

* **检查 AI 工具访问权限。** 如果工具返回 "tool access is not enabled for this application"：

  OneSignal 尚未为您的 OneSignal 登录开启 AI 工具访问权限。请联系 OneSignal 支持团队。

* **重启您的 AI 工具**并开始新会话。这可以解决大多数暂时性的连接问题。

## 工具 \\

请浏览以下工具。工具发现取决于您的 OneSignal 应用或账户是否启用了 MCP。每个操作还会检查您的 OneSignal 应用权限。

### 应用（2 个工具） \\

| 操作 | 工具 |
| - | - |
| 列出已验证用户可以访问的应用 | `list_apps` |
| 检查应用启用了哪些消息渠道 | `get_app_channel_availability` |

### Journeys（9 个工具） \\

| 操作 | 工具 |
| - | - |
| 列出应用的 Journeys | `list_journeys` |
| 查看 Journey 的结构和当前并发键 | `get_journey` |
| 查看 Journey、步骤、分支和消息统计 | `get_journey_stats` |
| 获取用于创建、复制或更新 Journey 或步骤的 JSON Schema | `get_journey_schema` |
| 将 Journey 创建为草稿 | `create_journey_draft` |
| 将 Journey 复制为新草稿 | `duplicate_journey` |
| 更新 Journey 字段或更改其状态 | `update_journey` |
| 更新单个 Journey 步骤 | `update_journey_node` |
| 永久删除 Journey | `delete_journey` |

> [card] [使用 MCP 管理 Journeys](https://documentation.onesignal.com/docs/en/mcp-journeys.md)
>
> 构建工具请求、获取 schema，并安全地应用 Journey 更改。

### 消息（3 个工具） \\

| 操作 | 工具 |
| - | - |
| 发送推送通知、电子邮件或短信 | `send_message` |
| 列出最近的通知 | `list_messages` |
| 查看通知详情和送达统计 | `view_message` |

要启动或更新 Live Activity，请参阅下方的 [Live Activities](#live-activities-2-tools)。

### 用户和订阅（12 个工具） \\

| 操作 | 工具 |
| - | - |
| 按别名查找用户 | `view_user` |
| 获取用户的身份别名 | `get_user_identity` |
| 按订阅 ID 获取身份 | `get_user_identity_by_subscription` |
| 创建带属性的新用户 | `create_user` |
| 更新用户属性（标签、语言等） | `update_user` |
| 添加或更新身份别名 | `create_or_update_alias` |
| 通过订阅 ID 添加别名 | `create_alias_by_subscription` |
| 添加推送、电子邮件或短信订阅 | `create_subscription` |
| 更新现有订阅 | `update_subscription` |
| 按令牌更新订阅 | `update_subscription_by_token` |
| 取消订阅电子邮件地址 | `unsubscribe_email` |
| 将订阅转移给其他用户 | `transfer_subscription` |

### 模板（4 个工具） \\

| 操作 | 工具 |
| - | - |
| 列出模板 | `list_templates` |
| 查看模板 | `get_template` |
| 创建模板 | `create_template` |
| 更新模板 | `update_template` |

### 细分（4 个工具） \\

| 操作 | 工具 |
| - | - |
| 列出细分 | `list_segments` |
| 查看细分及其筛选条件 | `get_segment` |
| 创建细分 | `create_segment` |
| 更新细分 | `update_segment` |

### Live Activities（2 个工具） \\

| 操作 | 工具 |
| - | - |
| 启动 iOS Live Activity | `start_live_activity` |
| 更新或结束 Live Activity | `update_live_activity` |

### 导出（2 个工具） \\

| 操作 | 工具 |
| - | - |
| 将订阅导出为 CSV | `export_subscriptions_csv` |
| 将通知受众活动导出为 CSV | `export_audience_activity_csv` |

### 自定义事件（2 个工具） \\

| 操作 | 工具 |
| - | - |
| 为用户创建自定义事件 | `create_custom_events` |
| 列出已编入索引的自定义事件定义 | `get_custom_events` |

### 电子邮件送达率（4 个工具） \\

| 操作 | 工具 |
| - | - |
| 检查电子邮件域名的 DNS 验证状态（SPF、DKIM、DMARC） | `get_email_domains` |
| 查看全应用的退信率和垃圾邮件投诉率 | `get_email_reputation` |
| 获取某个域名按收件服务商划分的送达率指标 | `get_provider_metrics` |
| 获取服务商送达率指标的时间序列 | `get_provider_metrics_timeseries` |

### 电子邮件预热（5 个工具） \\

| 操作 | 工具 |
| - | - |
| 检查发送是否需要 IP 或域名预热 | `check_send_volume` |
| 根据细分和筛选条件估算收件人数 | `estimate_recipient_count` |
| 获取推荐的分阶段预热计划 | `recommended_warm_up_schedule` |
| 将预热计划应用到草稿活动 | `apply_warm_up_schedule` |
| 列出当前正在进行的预热计划 | `get_active_warm_up_schedules` |

### 分析和实用工具（4 个工具） \\

| 操作 | 工具 |
| - | - |
| 查看成果分析 | `view_outcomes` |
| 检查服务器健康状况 | `onesignal_health` |
| 查看服务器配置 | `onesignal_config` |
| 查看所有工具的参考概览 | `onesignal_reference_overview` |

## 安全与防护措施 \\

* OneSignal 将 `send_message` 标记为高影响工具，因此遵循工具注解的 AI 工具可能会在运行前要求确认。
* `send_message` 会在发送前验证定向：每个请求只能使用一种定向方式，并且筛选条件有数量上限。
* OneSignal 会在执行前验证输入，包括标识符、电子邮件地址和电话号码。
* 有关 Journey 并发要求、生命周期控制以及写入结果不确定时的恢复，请参阅 [Journey 请求指南](https://documentation.onesignal.com/docs/en/mcp-journeys.md)。
* OneSignal 按每个 OneSignal 登录开启或关闭 AI 工具访问权限。
* MCP 服务器不会存储您的客户数据（订阅者、消息、导出）。

## 限制和使用 \\

连接 OneSignal 是免费的。每个操作都会计入您正常的 OneSignal API 使用限制。您的 AI 提供商的套餐可能会产生其自身的费用。

* 工具调用有速率限制，以防止工具陷入失控循环。
* 连接遵循已登录用户的权限，可以访问该用户能够管理的所有 OneSignal 应用。
* 在实用工具以外的工具可以使用之前，OneSignal 可能需要为您的登录开启 AI 工具访问权限。

## FAQ \\

### 我需要 REST API 密钥吗？ \\

不需要。每个连接都使用 OneSignal OAuth。您通过浏览器登录并批准访问，因此无需复制、存储或轮换 API 密钥。

### 如何使用多个 OneSignal 应用？ \\

一个连接即可涵盖您的 OneSignal 账户能够管理的所有应用。调用 `list_apps` 查找应用 ID。您不需要为每个应用单独配置。

### 我可以连接仅支持本地 stdio 服务器的 AI 工具吗？ \\

不可以。OneSignal MCP 服务器是通过 HTTP 访问的远程服务器。您的 AI 工具必须支持带 OAuth 的远程 MCP 服务器。

### 如何撤销 AI 工具的访问权限？ \\

在 OneSignal 中前往 **[Settings > Account settings > Connected apps](https://dashboard.onesignal.com/settings/connected-apps)** 并撤销该连接。撤销连接不会影响您队友的连接。

## 相关页面 \\

> [card] [在 Claude 和 ChatGPT 中使用 OneSignal](https://documentation.onesignal.com/docs/en/onesignal-in-claude-chatgpt.md)
>
> 从 Claude 或 ChatGPT 目录安装 OneSignal。

> [card] [使用 MCP 管理 Journeys](https://documentation.onesignal.com/docs/en/mcp-journeys.md)
>
> 从您的 MCP 客户端创建草稿、更新 Journey 步骤并管理 Journey 状态。

> [card] [REST API 概述](https://documentation.onesignal.com/reference/rest-api-overview.md)
>
> OneSignal MCP 服务器所调用端点的参考。

> [card] [创建消息 API](https://documentation.onesignal.com/reference/create-message.md)
>
> `send_message` 背后的端点参考。

> [card] [AI 数据实践](https://documentation.onesignal.com/docs/en/ai-data-practices.md)
>
> OneSignal 如何为 AI 功能和已连接的 AI 工具处理数据。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.