如何在 Claude、Cursor 或任何 Agentic Harness 中设置 PushEngage MCP 服务器

您使用 Claude Desktop、Claude Code 或 Cursor 的时间比使用 PushEngage 仪表板的时间还长。每次您需要查看点击率或发送通知时，您都需要切换到实际工作发生的窗口。PushEngage MCP 设置弥合了这一差距：一个 npx 命令，一次浏览器登录，然后 PushEngage 的工具就位于您已经用来编写代码、调试工作流或回答团队问题的同一个聊天会话中。

这是完整的设置指南：安装、两个值得了解的环境变量、首次登录以及在连接不正常工作时导致连接中断的三个具体问题。到最后，您将拥有一个已通过身份验证的会话，并已选择一个站点，而不仅仅是一个绿色的“已连接”指示器。

连接后您将能够做什么

@pushengage/mcp 在 10 个域中提供了 27 个工具，一旦您针对某个站点进行了身份验证，所有这些工具都只需一句话即可访问，而不是通过仪表板点击。以下是设置完成后的一些示例：

• 立即发送推送通知，安排在特定时间发送，或设置定期发送 — 如果您要求，可以在每个订阅者的本地时区发送。
• 在两个标题之间运行 A/B 测试，并在结果出来后让助手报告点击率。
• 根据自然语言描述构建细分或受众群组，而不是使用规则界面。
• 以终生汇总或逐日时间序列的形式提取分析数据。
• 列出您的自动回复邮件系列、触发式营销活动和工作流，以检查实际正在运行的内容。
• 读取您站点的设置、服务工作者配置和聊天小部件设置。

所有这些都不需要助手拥有您的 PushEngage 密码，也不需要您离开编辑器或终端。PushEngage 为 150 多个国家/地区的 25,000 多个企业主提供此集成，在过去 30 天内发送了 152 亿条通知。MCP 服务器与运行该流量的生产 API 相同，而不是沙盒演示。

开始之前：您需要什么

三件事，您可能已经拥有其中至少两件：

1. 一个 PushEngage 帐户 — 免费或付费，至少添加了一个站点。MCP 服务器不会为您创建站点；它在您已在 PushEngage 仪表板中设置的站点上运行。
2. Node.js 18 或更高版本 — 助手通过 npx 运行服务器，npx 随 Node 一起提供。在终端中使用 node -v 进行检查。
3. 支持 MCP 的客户端 — Claude Desktop、Claude Code、Cursor 或任何其他通过标准输入/输出 (stdio) 使用 MCP 的客户端。

在开始编辑配置文件之前，有一点需要明确说明：@pushengage/mcp 在您的本地机器上通过 stdio 运行。没有远程服务器可供指向，也没有托管的连接器 URL。客户端启动进程，然后该进程代表您与 PushEngage 的 API 通信。如果某个设置指南告诉您粘贴远程端点，那么它指的是与此不同的 MCP 服务器类型。

在 Claude Desktop、Claude Code 和 Cursor 中设置服务器

无需全局安装。npx 在您的客户端首次启动它时按需获取 @pushengage/mcp，使用的确切命令是 npx -y @pushengage/mcp。您将此命令添加到客户端的 MCP 配置中，然后重新启动客户端，服务器就会出现在您的工具列表中。

每个客户端将配置保存在不同的位置。

Claude Desktop

在 macOS 上编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（或您平台上的等效路径）：

{
  "mcpServers": {
    "pushengage": {
      "command": "npx",
      "args": ["-y", "@pushengage/mcp"]
    }
  }
}

重新启动 Claude Desktop。“pushengage”服务器应出现在您的工具列表中。

Cursor

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "pushengage": {
      "command": "npx",
      "args": ["-y", "@pushengage/mcp"]
    }
  }
}

Claude Code

Claude Code 与 Claude Desktop 和 Cursor 一样，通过 stdio 使用 MCP，因此如果您直接编辑其 MCP 配置文件，相同的 command/args 结构也适用。如果您不想手动编辑 JSON，Claude Code 也通过其自己的 claude mcp add CLI 命令接受服务器，这是 Claude Code 的通用行为，而不是 PushEngage 特有的。如果选择此方法，请查阅 Claude Code 自己的文档以了解确切的标志语法。

任何其他 MCP 客户端

如果您的客户端不是以上三种之一，那么底层的要求在任何地方都是相同的：将其配置为运行 npx -y @pushengage/mcp 作为 stdio 服务器。这就是全部的安装步骤，无论哪个客户端读取配置。

命名连接和隔离令牌：PE_MCP_CLIENT_NAME 和 PE_MCP_CONFIG_PATH

除了安装步骤之外，不需要其他配置。服务器默认与 PushEngage 的生产 API 通信；有两个环境变量可用于不太常见的设置：

环境变量	默认	目的
PE_MCP_CLIENT_NAME	AI 助手	在 PushEngage 授权屏幕上显示的标签，表示请求访问的应用程序。如果需要更具体的内容，例如 "Claude Desktop"，请设置它。
PE_MCP_CONFIG_PATH	~/.pushengage/mcp.json	存储访问令牌的位置。设置此项可同时运行多个 PushEngage 帐户。必须是绝对路径 — 不支持 ~ 扩展。

大多数单帐户设置永远不需要更改这两个变量。PE_MCP_CLIENT_NAME 是一个外观上的便利设置，如果您希望授权屏幕显示比“AI 助手”更易读的名称（当您是点击授权的人时），它会很有用。PE_MCP_CONFIG_PATH 在您需要第二个、单独的令牌文件时才重要，这正是接下来介绍的情况。

首次运行：登录并选择站点

身份验证是基于浏览器的，因此助手永远看不到您的 PushEngage 密码。该流程分为三个步骤，值得深入了解每个步骤在底层实际调用了什么：

1. 要求助手登录。 用通俗的话说：“登录我的 PushEngage。” 这会调用 pushengage_auth_login，它会打开一个浏览器标签页到 PushEngage 授权页面。
2. 点击授权。 仪表板将令牌作为 POST 请求发送到服务器 — 它永远不会出现在 URL、浏览器历史记录或访问日志中。该令牌以 0600 权限本地保存，仅供您的用户读取。
3. 要求助手显示您的站点，然后选择一个。 “显示我的 PushEngage 站点”调用 pushengage_list_sites；“使用站点 12345”调用 pushengage_select_site。选择会跨重启被记住，并且每个站点范围的工具都会对其进行操作，除非您明确传递了不同的 site_id。

涉及的工具，按名称分类：

工具	目的
pushengage_auth_login	打开浏览器到 PushEngage 并成功后存储令牌。
pushengage_auth_status	显示您是否已通过身份验证以及当前选择了哪个站点。
pushengage_list_sites	列出您的帐户可以访问的 PushEngage 站点。
pushengage_select_site	设置其他工具将操作的当前站点。

选择站点后，运行 pushengage_auth_status（询问“我的 PushEngage 身份验证状态是什么”就足够了），并在尝试其他任何操作之前确认它报告了已通过身份验证的会话和已选定的站点。这才是设置的真正终点，而不是客户端首次显示服务器已连接的那一刻。

故障排除，按原因分类

大多数连接问题都可以追溯到三个特定原因之一。按此顺序进行诊断。

服务器根本无法连接，并且您的客户端显示“连接已关闭”。 这几乎总是 PATH 问题，而不是服务器中的错误。Claude Desktop、Cursor 和类似的客户端从您的 Dock 或 Finder 启动，而不是从终端启动，因此它们永远不会加载您的 shell 的启动文件。如果 Node 是通过版本管理器（nvm、fnm、volta）安装的，客户端根本找不到 npx。进程永远不会启动，您会收到通用的连接错误，而不是清晰的“命令未找到”。在终端中运行 which npx 以获取绝对路径，然后直接将您的客户端指向它：

{
  "mcpServers": {
    "pushengage": {
      "command": "/absolute/path/from/which-npx",
      "args": ["-y", "@pushengage/mcp"],
      "env": {
        "PATH": "/absolute/folder/containing/that/npx:/usr/bin:/bin:/usr/sbin:/sbin"
      }
    }
  }
}

编辑后重新启动客户端。如果 which npx 打印出 /usr/local/bin 或 /opt/homebrew/bin 下的路径，则版本管理器可能不是您的问题；请检查客户端自己的 MCP 日志以获取实际错误。

[AUTH_EXPIRED]。 您的令牌已过期。要求助手重新登录 — 这就是全部的修复方法。

[NO_SITE_SELECTED]。 您已通过身份验证，但尚未选择任何站点。请调用 pushengage_list_sites，然后请求使用返回的站点之一，之后再尝试任何站点范围内的工具。

还有一种情况虽然不是错误，但值得了解：如果浏览器没有自动打开，您可能处于无头或远程会话（SSH、容器）中。授权 URL 会打印到运行服务器的终端。请手动打开它。

运行多个 PushEngage 帐户或客户端

如果您为多个品牌管理 PushEngage，或者您是一家代理机构，对多个客户帐户使用 MCP，那么解决方法是使用前面提到的 PE_MCP_CONFIG_PATH：在两个不同的名称下注册服务器，每个名称都有自己的路径，以避免令牌冲突。

{
  "mcpServers": {
    "pushengage-client-a": {
      "command": "npx",
      "args": ["-y", "@pushengage/mcp"],
      "env": {
        "PE_MCP_CONFIG_PATH": "/Users/you/.pushengage/mcp-client-a.json",
        "PE_MCP_CLIENT_NAME": "Claude Desktop (Client A)"
      }
    },
    "pushengage-client-b": {
      "command": "npx",
      "args": ["-y", "@pushengage/mcp"],
      "env": {
        "PE_MCP_CONFIG_PATH": "/Users/you/.pushengage/mcp-client-b.json",
        "PE_MCP_CLIENT_NAME": "Claude Desktop (Client B)"
      }
    }
  }
}

分别在每个服务器名称下登录，每次在浏览器中授权您选择的 PushEngage 帐户。每个服务器条目都保留自己的令牌文件，因此在客户端帐户之间切换取决于您调用的工具名称，而不是每次都重新登录。如果这是您的实际用例，本系列文章中有关于从一个 AI 助手运行多个 PushEngage 客户端帐户的完整演练。

连接后该做什么

在完成身份验证并选择站点后，这 27 个工具可以分为几组实用的类别，值得了解它们的名称，而不仅仅是数量。

对于日常的广告系列管理工作，本系列文章介绍了如何从 AI 助手发送和安排推送通知，而不是通过仪表板，以及如何对推送通知进行 A/B 测试并让 AI 根据点击率选择获胜者。要构建您的列表，有一份完整的指南可以帮助您用通俗的英语构建订阅者细分。

对于衡量，通过 AI 助手读取推送通知分析介绍了生命周期摘要和逐日时间序列。这些与 A/B 测试结果或广告系列发送值得报告（而不仅仅是运行）的分析工具相同。本系列文章还介绍了审核自动回复广告系列和工作流以检查哪些是实际活动的，以及管理在网站上显示 WhatsApp 和其他频道的聊天小部件。

对于站点级别的操作，从 AI 助手更改 PushEngage 站点设置涵盖了时区、地理位置和 Service Worker 配置。如果您正在为多个 PushEngage 帐户进行设置，那么上面链接的关于从一个 AI 助手运行多个 PushEngage 客户端帐户的面向代理机构的文章，比本指南中的配置示例更深入。

如果您正在为技术水平较低的人（例如，希望 AI 助手能够处理 PushEngage 日常工作而无需自己触摸配置文件）的创始人进行设置，那么非技术创始人使用 PushEngage MCP 的第一周是为该读者撰写的相同设置的叙述版本。

设置本身的工作方式与您的 PushEngage 计划无关。每个 PushEngage 计划，包括免费套餐，都支持 MCP 服务器。如果您在连接任何内容之前决定哪个计划适合您，PushEngage 的定价页面会显示当前套餐。