PubNub Model Context Protocol (MCP) Server for Cursor IDE

PubNub MCP 服务

一个托管的模型上下文协议（MCP）服务，向由大模型驱动的工具提供 PubNub SDK 文档和 PubNub API 资源。这有助于提升大模型 AI Agent 理解和使用 PubNub SDK 与 API 的能力。使用 HTTP 传输和 OAuth 身份验证。

功能

• 📚 全面的 SDK 文档 - 查阅 20 多种编程语言的详细文档、代码示例和实现指南，包括 JavaScript、Python、Java、Swift、Kotlin、C#、Ruby、Go 等
• 🏗️ 应用和 Keyset 管理 - 创建、配置和管理 PubNub 应用与 keyset，支持消息持久化、文件共享、在线状态跟踪和应用上下文等功能
• 💬 实时通信 - 在频道间收发消息，实现实时聊天、通知和实时更新，同时支持消息和轻量级信号
• 👥 用户和频道管理 - 管理用户资料、频道元数据和成员关系，提供完整的增删改查操作，用于构建社区和社交功能。此外，还可以在 PubNub Admin Portal 中查看和管理用户资料、频道及成员关系（需要 Manage Premium）。
• 📍 在线状态和活动跟踪 - 监控用户实时在线状态，查看频道中哪些用户在线，并跟踪应用中的用户活动
• 📊 实时决策和分析 - 在关键时刻触发正确的操作、衡量其影响，并随条件变化进行调整——全部实时完成。需要 Illuminate。
• 📈 频道、用户和消息分析 - 发现应用活动汇总数据中的模式，从热门频道和国家分布，到新用户与回访用户及设备分布，帮助了解参与度、使用情况和性能。此外，无需 Manage Premium 即可在 PubNub Admin Portal 中查看有限的指标；完整分析功能需要 Manage Premium。
• 🔍 使用情况和监控 — 跟踪应用和 keyset 的计费使用情况，查看当前和历史用量，并导出报告以了解成本来源。
• 🔧 多平台集成 - 适用于 Cursor、Visual Studio Code、Claude Code 和其他兼容 MCP 的 AI 助手
• ⚡ 开发者体验 - 使用 TypeScript 构建，确保类型安全，并包含测试基础设施

快速开始

托管服务由 PubNub 管理，是最简单的入门方式——无需安装，且通过 OAuth 自动完成身份验证。如果你的 AI 工具不支持远程 MCP 服务，请改用本地安装版本（npx @pubnub/mcp@latest）。

注意： 要切换到托管服务（https://mcp.pubnub.com），请先从 AI 客户端中移除旧的本地配置，然后按照下方的设置步骤操作。

托管的 PubNub MCP 服务

将 AI 助手连接到 https://mcp.pubnub.com，无需安装。身份验证通过 OAuth 自动完成。

VS Code

点击上方按钮，然后选择 在 Visual Studio Code 中打开。返回 VS Code 后，点击 安装，然后选择要授权的组织并点击 允许访问。

或者，手动将以下内容添加到 VS Code 的 settings.json 中：

{
  "mcp": {
    "servers": {
      "pubnub": {
        "url": "https://mcp.pubnub.com"
      }
    }
  }
}

在 VS Code 文档中了解详情

Cursor

点击上方按钮，然后选择 Open Cursor。在 Cursor 中，点击 Install，选择要授权的组织，然后点击 Allow access。前往 Cursor Settings → Tools & MCP，确认已启用 PubNub。

或者，手动将以下内容添加到 .cursor/mcp.json（或用于全局配置的 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "pubnub": {
      "url": "https://mcp.pubnub.com"
    }
  }
}

保存文件后，会显示一条通知。点击 Enable 以激活 MCP 服务。在 Cursor 文档中了解更多

Claude Code

在终端中运行：

claude mcp add --scope user --transport http pubnub https://mcp.pubnub.com

然后运行 claude 打开 Claude Code，并输入 /mcp。选择 pubnub，然后选择 authenticate，再点击 Allow access 完成授权。在 Claude Code 文档中了解更多

Claude Desktop

**注意：**以下说明适用于 Pro 和 Max 计划。对于 Enterprise 计划，设置由组织管理员配置。详情请参阅 Anthropic 文档。

1. 在 Claude Desktop 中，前往 Customize → Connectors。
2. 点击 +，然后选择 Add custom connector。
3. 输入 https://mcp.pubnub.com 作为连接器 URL。
4. 按提示完成 OAuth 登录。

在 Claude Desktop 文档中了解更多

Codex

在终端中运行：

codex mcp add pubnub --url https://mcp.pubnub.com

然后运行 codex mcp login pubnub 进行身份验证，选择要授权的组织，然后点击 Allow access。在 Codex 文档中了解更多

Codex Desktop

1. 前往 Settings → MCP servers，然后点击 + Add server。
2. 选择 Streamable HTTP 作为传输类型。
3. 输入 https://mcp.pubnub.com 作为服务 URL。
4. 按照 OAuth 登录提示完成授权。

在 Codex Desktop 文档中了解更多

Gemini CLI

在终端中运行：

gemini mcp add pubnub --scope user --transport http https://mcp.pubnub.com

然后运行 gemini 打开 Gemini CLI，并运行 /mcp auth pubnub 进行身份验证。在 Gemini CLI 文档中了解更多

OpenCode

将以下内容添加到 ~/.config/opencode/config.json：

{
  "mcp": {
    "pubnub": {
      "type": "remote",
      "url": "https://mcp.pubnub.com",
      "enabled": true
    }
  }
}

然后运行 opencode mcp auth pubnub 进行身份验证。在 OpenCode 文档中了解更多

本地 PubNub MCP 服务

如果你的 AI 工具不支持远程 MCP 服务，请使用以下命令在本地运行服务：

npx @pubnub/mcp@latest

API 密钥

开始之前，我们强烈建议你在 PubNub Admin Portal 中创建 Service Integration，并向 MCP 服务提供你的 API 密钥。虽然不提供密钥也能使用一些基本功能，但添加 API 密钥可以解锁更多功能。或者，请参阅本地服务配置，了解如何配置服务以使用单个 PubNub 密钥集。

MCP 服务的安装过程取决于你使用的 AI 助手。对于标准设置，你需要安装 Node.js（v20.0.0 或更高版本）。

VS Code

只需点击上方链接，然后在出现的页面中选择“在 Visual Studio Code 中打开”。返回 VS Code 后，点击“安装”。系统会提示你输入 PubNub API Key。输入后，MCP 服务即可使用。有关其他配置选项，请参阅本地服务配置。

Cursor

点击上方链接，然后在出现的页面中选择“打开 Cursor”。返回 Cursor 后，会出现“安装 MCP 服务？”提示。请确保提供保存 PubNub API Key 的变量值，然后点击“安装”。现在即可使用 MCP 服务。有关其他配置选项，请参阅本地服务配置。

Claude Code

安装 Claude Code 后，运行此命令即可将 MCP 添加到配置中。请务必替换 <your-api-key> 的值：

claude mcp add pubnub --env PUBNUB_API_KEY=<your-api-key> --scope user --transport stdio -- npx -y @pubnub/mcp@latest

服务已添加到“User”范围，这意味着它将在所有项目中可用。有关其他配置选项，请参阅本地服务配置。

Codex

安装 Codex 后，运行此命令即可将 MCP 添加到配置中。请务必替换 <your-api-key> 的值：

codex mcp add pubnub --env PUBNUB_API_KEY=<your-api-key> -- npx -y @pubnub/mcp@latest

有关其他配置选项，请参阅本地服务配置。

Gemini CLI

Gemini CLI 不支持自动安装 MCP。你需要手动编辑 settings.json 文件并添加以下部分。请务必替换 <your-api-key> 的值：

"mcpServers": {
  "pubnub": {
    "command": "npx",
    "args": [
      "-y",
      "@pubnub/mcp@latest"
    ],
    "env": {
      "PUBNUB_API_KEY": "<your-api-key>"
    }
  }
}

有关其他配置选项，请参阅 PubNub 文档中的本地服务配置部分。

开发

先决条件

• Node.js >= 20.0.0

本地运行

npm install
npm run dev

环境变量

变量	描述	必需
PORT	HTTP 服务端口（默认：3000）	否
MCP_OAUTH_ENABLED	启用 OAuth 身份验证	是（生产环境需要）
OAUTH_ISSUER	OAuth 授权服务器 URL	启用 OAuth 时
OAUTH_CLIENT_ID	OAuth 客户端 ID	启用 OAuth 时
OAUTH_CLIENT_SECRET	OAuth 客户端密钥	启用 OAuth 时
ADMIN_API_RESOURCE_URL	Admin API 资源标识符	启用 OAuth 时
MCP_RESOURCE_URL	MCP 资源 URL	启用 OAuth 时
MCP_CLOUD_MODE	云部署模式	否
MCP_SESSION_SUPPORT	启用会话持久化	否
ADMIN_API_V2_URL	覆盖 Admin API v2 端点	否
PUBNUB_ORIGIN	覆盖 PubNub 源站	否
SDK_DOCS_API_URL	覆盖文档 API 端点	否

测试

npm run test:unit        # Unit tests
npm run test:integration # Integration tests (requires build)
npm run test:coverage    # Coverage report

API 参考

此 PubNub MCP 服务提供了一套全面的工具、资源和提示词，帮助你构建实时应用。以下是所有可用功能的完整参考：

工具

文档访问

• get_sdk_documentation - 获取特定编程语言和功能的 PubNub Core SDK 文档
• get_chat_sdk_documentation - 获取特定编程语言和功能的 PubNub Chat SDK 文档
• how_to - 获取适用于特定用例和集成的 PubNub 概念指南
• write_pubnub_app - 获取 PubNub 最佳实践指南，涵盖架构、安全性、频道建模和优化
• get_sdk_migration_guide - 获取 SDK 版本迁移指南
• get_general_migration_guide - 获取通用平台迁移指南

应用与密钥集管理

• manage_apps - 管理 PubNub 应用（列出、创建、更新）
• manage_keysets - 管理 PubNub 密钥集（获取、列出、创建、更新）
• get_usage_metrics - 获取账户、应用或密钥集的使用指标

实时通信

• send_pubnub_message - 实时向 PubNub 频道发送消息或轻量级信号
• subscribe_and_receive_pubnub_messages - 订阅频道并接收实时消息，可配置超时和消息数量限制
• get_pubnub_messages - 获取一个或多个 PubNub 频道的历史消息
• get_pubnub_presence - 使用 HereNow（频道占用情况）或 WhereNow（用户所在频道）获取在线状态数据
• manage_app_context - 使用完整的 CRUD 操作管理用户、频道和成员资格的 PubNub App Context（Objects API）

Illuminate 分析与自动化

• manage_illuminate - 管理 PubNub Illuminate 资源（业务对象、查询、指标、决策、仪表板），支持完整的 CRUD、激活、分析查询、操作日志检查和测试数据发布

Insights 分析

• insights - 查询 PubNub Insights 的聚合分析指标：唯一频道数和用户数、消息量、前 N 项排名（频道、用户、消息类型）、国家/地区细分、新用户与回访用户趋势、用户时长以及设备类型分布。需要具有账户级 Insights Read 访问权限的 Service Integration API 密钥，以及 Insights Premium 层级。

提示词

医疗健康与 HIPAA 合规

• hipaa-chat-short - 快速提示词，用于创建符合 HIPAA 要求的聊天应用
• hipaa-chat-long - 详细提示词，用于创建支持 Pub/Sub、Presence 和 App Context 的 HIPAA 合规聊天应用

React 开发

• react-app-short - 使用 PubNub Pub/Sub 和 Presence 搭建 React 应用框架
• react-app-long - 功能全面的 React 应用，支持实时消息、在线状态指示器和用户元数据

游戏应用

• gamelobby-short - 构建支持聊天和在线状态的多人游戏大厅
• gamelobby-long - 构建高级多人游戏大厅，支持团队分配和实时功能

OEM 与多租户解决方案

• oem-client-management - 为 OEM 客户端部署创建应用并配置密钥集
• multi-tenant-onboarding-short - 为 SaaS 应用实现自动化租户入驻
• multi-tenant-onboarding-long - 实现企业级多租户入驻，支持数据隔离和错误处理

Illuminate 分析与自动化

• illuminate-spam-detection - 设置 Illuminate 垃圾信息检测流水线，并配置逐步升级的审核措施
• illuminate-reward-engagement - 为现场活动和游戏构建 Illuminate 互动奖励流水线
• illuminate-use-case - 引导设置任意 Illuminate 分析与自动化用例
• illuminate-test-verify - 端到端测试并验证现有 Illuminate 配置

洞察分析

• insights-snapshot - 快速获取指定日期范围的高级分析快照：不重复的频道数、不重复的用户数、消息量、按消息数排名前 20 的频道，以及异常提示
• insights-channel-analysis - 深入分析按排名类别划分的热门频道、频道命名模式，以及跨类别互动对比
• insights-user-growth - 新用户与回访用户趋势、按日／周／月划分的数据、热门国家，以及鲸鱼用户识别
• insights-engagement-deep-dive - 平均用户时长、会话长度区间直方图、按用户分钟数排名的热门频道，以及发布者、订阅者和不重复用户的设备类型细分

资源

• pubnub_sdk_docs - 通过 URI 方案访问 PubNub SDK 文档：pubnub-docs://sdk/{language}/{feature}

支持的语言：asyncio、c-core、c-sharp、dart、freertos、go、java、javascript、kotlin、mbed、objective-c、php、posix-c、posix-cpp、python、ruby、rust、swift、unity、unreal、windows-c、windows-cpp

支持的功能：access-manager、access-manager-v2、channel-groups、configuration、encryption、files、message-actions、misc、mobile-push、objects、presence、publish-and-subscribe、storage-and-playback

• pubnub_chat_sdk_docs - 通过 URI 方案访问 PubNub Chat SDK 文档：pubnub-docs://chat-sdk/{language}/{feature}

支持的语言：javascript、kotlin、swift、unity、unreal

支持的功能：channels-create、channels-delete、channels-details、channels-invite、channels-join、channels-leave、channels-list、channels-membership、channels-references、channels-typing-indicator、channels-updates、channels-watch、connection-management、custom-events、error-logging、messages-delete、messages-details、messages-drafts、messages-files、messages-forward、messages-history、messages-links、messages-moderation、messages-pinned、messages-quotes、messages-reactions、messages-read-receipts、messages-restore、messages-send-receive、messages-threads、messages-unread、messages-updates、moderation、push-notifications、users-create、users-delete、users-details、users-list、users-mentions、users-moderation、users-moderation-user、users-permissions、users-presence、users-updates、utility-methods