PubNub Model Context Protocol (MCP) 服务器用于 Cursor IDE

此仓库提供了一个基于 CLI 的 Model Context Protocol (MCP) 服务器，该服务器将 PubNub SDK 文档和 PubNub API 资源暴露给由大语言模型（LLM）驱动的工具。这提高了 LLM AI 代理理解和与 PubNub 的 SDK 和 API 交互的能力。

功能

• 通过 STDIN/STDOUT 上的 JSON-RPC 暴露用于与 PubNub 交互的工具。
• 获取官方 PubNub SDK 文档（HTML → Markdown），支持以下语言：JavaScript、Python、Java、Go、Ruby、Swift、Objective-C、C#、PHP、Rust、Unity、Kotlin、Unreal。
• API 参考部分包括：配置、发布与订阅、存在检测、访问管理器、频道组、存储与回放、移动推送、对象、文件、消息操作、杂项、函数。
• 从 resources 目录中的本地 markdown 文件获取 PubNub 概念指南和操作文档（例如，pubnub_concepts、pubnub_features、pubnub_security、how_to_send_receive_json、how_to_encrypt_messages_files 等）。
• 使用 publish_pubnub_message 向 PubNub 频道发布消息，并返回时间戳。
• 使用 get_pubnub_messages 从一个或多个频道获取历史消息，以 JSON 格式返回消息内容和元数据。
• 使用 get_pubnub_presence 获取频道和频道组的实时存在信息（占用计数、订阅者 UUID）。
• 使用 write_pubnub_app 生成创建 PubNub 应用程序的逐步说明，包括在多种语言中初始化 PubNub SDK 的代码片段。
• 环境变量配置：支持 PUBNUB_PUBLISH_KEY 和 PUBNUB_SUBSCRIBE_KEY 用于验证 SDK 操作。
• 使用 jsdom 和 turndown 将远程 HTML 文章转换为 Markdown，以确保文档格式一致。
• 通过 Zod 模式对所有工具参数进行输入验证，确保强大的错误处理。
• 利用 Model Context Protocol SDK (@modelcontextprotocol/sdk) 提供可扩展的工具定义，包括 McpServer 和 StdioServerTransport。

示例提示

• "编写一个 PubNub 应用程序，让用户可以观看带有内置多用户聊天功能的流媒体视频。"
• "编写一个 PubNub 应用程序，实现带地图的按需杂货配送。"
• "编写一个 PubNub 应用程序，实时跟踪包裹的位置。"
• "编写一个 PubNub 应用程序，实时显示天气预报。"
• "编写一个 PubNub 应用程序，让用户可以与朋友一起玩多人游戏。"
• "编写一个 PubNub 应用程序，显示实时股票价格和新闻更新。"
• "编写一个 PubNub 应用程序，让用户可以创建和分享播放列表。"
• "构建一个 PubNub JavaScript 应用程序，订阅 my_channel 频道并将消息记录到控制台。"
• "向 my_channel 频道发布一条消息，内容为 Hello, PubNub!。"
• "显示 PubNub JavaScript SDK 中 subscribe() 方法的文档。"
• "列出所有可用的 PubNub 函数。"
• "获取 Python SDK 中 publish() 方法的文档。"
• "获取 test 频道的消息历史。"
• "检索 test 频道和 default 频道组的存在信息（占用情况和 UUID）。"

这需要 Node.js (>= 18) 和 npm (https://nodejs.org/)。 npx 会自动获取并运行最新的 MCP 服务器。

先决条件

• Node.js (>= 18) 和 npm
• 支持 MCP 的 Cursor IDE
• （可选）PubNub 账户和 API 密钥，用于实时示例

安装

推荐的方式是通过 npx 在本地运行 PubNub MCP 服务器或将它添加到 Cursor IDE：

bash npx -y @pubnub/mcp

配置

Cursor 必须处于 AGENT 模式才能使用 MCP 服务器。

Cursor IDE 通过 JSON 配置文件发现 MCP 服务器。全局或按项目配置 PubNub MCP 服务器。### 全局配置

编辑或创建 ~/.cursor/mcp.json 文件：

json { "mcpServers": { "pubnub": { "command": "npx", "args": ["-y", "@pubnub/mcp"], "env": { "PUBNUB_PUBLISH_KEY": "YOUR_PUBLISH_KEY", "PUBNUB_SUBSCRIBE_KEY": "YOUR_SUBSCRIBE_KEY" } } } }

项目配置

在您的项目目录中，创建 .cursor/mcp.json 文件：

json { "mcpServers": { "pubnub": { "command": "npx", "args": ["-y", "@pubnub/mcp"], "env": { "PUBNUB_PUBLISH_KEY": "YOUR_PUBLISH_KEY", "PUBNUB_SUBSCRIBE_KEY": "YOUR_SUBSCRIBE_KEY" } } } }

基于 Docker 的配置

如果您希望通过 Docker 运行 MCP 服务器，请将 PubNub 密钥设置为环境变量：

bash export PUBNUB_PUBLISH_KEY=YOUR_PUBLISH_KEY export PUBNUB_SUBSCRIBE_KEY=YOUR_SUBSCRIBE_KEY

然后配置您的 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）文件：

json { "mcpServers": { "pubnub": { "command": "docker", "args": [ "run", "-i", "-e", "PUBNUB_PUBLISH_KEY", "-e", "PUBNUB_SUBSCRIBE_KEY", "pubnub/pubnub-mcp-server" ] } } }

• command 指定启动 MCP 服务器的可执行文件。
• args 指定传递给命令的参数。
• env 设置服务器进程的环境变量。

在 Cursor IDE 中使用

1. 重启 Cursor IDE 或打开一个新会话。
2. 打开 MCP 设置面板并验证 pubnub 服务器是否列在 可用工具和资源 下。
3. 在聊天中调用可用资源：
   • pubnub://docs/javascript — 获取 PubNub JavaScript SDK 文档
   • pubnub://docs/python — 获取 PubNub Python SDK 文档
   • pubnub://docs/java — 获取 PubNub Java SDK 文档
   • pubnub://functions — 列出 PubNub 函数（来自 resources/pubnub_functions.md 的静态内容）
4. 当提示时批准资源执行，或在设置中启用 自动运行 以信任资源。

Claude 代码

shell

如果您有 node >= 18，则安装 MCP 服务器

claude mcp add pubnub -e PUBNUB_PUBLISH_KEY=your_publish_key -e PUBNUB_SUBSCRIBE_KEY=your_subscribe_key -- npx -y @pubnub/mcp

如果您有 node < 18 并需要指向 node 的完整路径

claude mcp add pubnub -e PUBNUB_PUBLISH_KEY=your_publish_key -e PUBNUB_SUBSCRIBE_KEY=your_subscribe_key -- /Users/stephen/.nvm/versions/node/v22.14.0/bin/node /Users/stephen/Projects/mcp-pubnub/index.js

使用 Docker 安装 MCP 服务器

确保您的 PubNub 密钥已设置为环境变量：

export PUBNUB_PUBLISH_KEY=your_publish_key export PUBNUB_SUBSCRIBE_KEY=your_subscribe_key

根据您的机器 CPU 架构，您可能需要指定目标平台。

例如：

docker run --platform linux/arm64 -i pubnub/pubnub-mcp-server

docker run --platform linux/amd64 -i pubnub/pubnub-mcp-server

claude mcp add pubnub -- docker run -i -e PUBNUB_PUBLISH_KEY=$PUBNUB_PUBLISH_KEY -e PUBNUB_SUBSCRIBE_KEY=$PUBNUB_SUBSCRIBE_KEY pubnub/pubnub-mcp-server

输出将是： shell Added stdio MCP server pubnub with command: npx -y @pubnub/mcp to local config

示例提示

shell claude "publish a message hi to the my_channel pubnub channel."

shell claude "publish a message hi to the my_channel pubnub channel."

╭───────────────────────────────────────────────────╮ │ ✻ Welcome to Claude Code research preview! │ │ │ │ /help for help, /status for your current setup │ │ │ │ cwd: /Users/stephen/Projects/mcp-pubnub │ ╰───────────────────────────────────────────────────╯

※ Tip: Press Option+Enter to send a multi-line message

publish a message hi to the my_channel pubnub channel.

⏺ I ll publish a message to the PubNub channel for you.

⏺ pubnub:publish_pubnub_message (MCP)(channel: "my_channel", message: "hi")… ⎿  Message published successfully. Timetoken: 17467422499409217

⏺ Message published successfully to "my_channel".移除MCP服务器，请使用：

shell claude mcp remove pubnub

使用Claude Desktop

如果您更喜欢在Claude Desktop中使用基于Docker的MCP服务器：

1. 确保您的PubNub密钥已在shell中导出： bash export PUBNUB_PUBLISH_KEY=your_publish_key export PUBNUB_SUBSCRIBE_KEY=your_subscribe_key

2. 在Claude Desktop的工具部分，添加一个名为pubnub的新工具。

3. 将命令设置为docker。

4. 将参数设置为： json [ "run", "-i", "-e", "PUBNUB_PUBLISH_KEY", "-e", "PUBNUB_SUBSCRIBE_KEY", "pubnub/pubnub-mcp-server" ]

注意： 在某些机器上（例如Apple Silicon），您可能需要指定Docker平台。 在Arguments数组中的"run"之后立即插入--platform linux/arm64（或--platform linux/amd64）。例如：

json [ "run", "--platform", "linux/arm64", "-i", "-e", "PUBNUB_PUBLISH_KEY", "-e", "PUBNUB_SUBSCRIBE_KEY", "pubnub/pubnub-mcp-server" ]

5. 保存配置。

Claude Desktop将通过Docker调用PubNub MCP服务器容器。

许可证

本项目根据MIT许可证发布。详情请参阅LICENSE文件。

故障排除

• 必须处于代理模式才能使用MCP服务器。
• 验证Node.js和npm是否已安装。
• 确保index.js具有执行权限。
• 检查command、args和env设置是否正确。
• 查看Cursor IDE日志以获取MCP启动错误。

直接JSON-RPC命令行使用

您可以直接通过STDIN/STDOUT使用JSON-RPC v2.0调用MCP服务器。 确保您的PubNub密钥已在环境中设置，例如： bash PUBNUB_PUBLISH_KEY=YOUR_PUBLISH_KEY PUBNUB_SUBSCRIBE_KEY=YOUR_SUBSCRIBE_KEY node index.js

一旦服务器运行（或一次性调用），可以通过管道将JSON传入node index.js来发送请求。示例： bash

1) 列出可用工具

echo {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
| node index.js

2) 读取PubNub JavaScript SDK文档

echo {"jsonrpc":"2.0","id":2,"method":"tools/call","params": {"name":"read_pubnub_sdk_docs","arguments":{"language":"javascript"}}}
| node index.js

3) 读取PubNub Functions资源文档（静态Markdown）

echo {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"read_pubnub_resources","arguments":{"document":"pubnub_functions"}}}
| node index.js

快速JSON-RPC示例

以下是使用STDIN/STDOUT获取PubNub SDK文档和发布消息的简化JSON-RPC v2.0命令行示例。

1) 获取PubNub JavaScript SDK文档

bash echo {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"read_pubnub_sdk_docs","arguments":{"language":"javascript"}}} | node index.js

2) 向PubNub频道发布消息

bash PUBNUB_PUBLISH_KEY=demo PUBNUB_SUBSCRIBE_KEY=demo echo {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"publish_pubnub_message","arguments":{"channel":"my_channel","message":"Hello, PubNub MCP JSON-RPC!"}}}
| node index.js

工具列表

• read_pubnub_sdk_docs: Retrieves official PubNub SDK documentation for a given programming language and API reference section. Call this tool whenever you need detailed SDK docs, code examples, or usage patterns. Returns documentation in markdown format.

• read_pubnub_chat_sdk_docs: Retrieves official PubNub Chat SDK documentation for a given Chat SDK language and topic section. Call this tool whenever you need detailed Chat SDK docs, code examples, or usage patterns. Returns documentation in markdown format.

• read_pubnub_resources: Retrieves PubNub conceptual guides and how-to documentation from markdown files in the resources directory. Call this tool whenever you need overviews, integration instructions, best practices, or troubleshooting tips for PubNub features. Specify the resource name to retrieve, such as pubnub_concepts, pubnub_features, pubnub_security, how_to_send_receive_json, how_to_encrypt_messages_files, etc.

• publish_pubnub_message: Publishes a message to a specified PubNub channel. Call this tool whenever you need to send data through PubNub. Provide the channel name and message payload. Returns a timetoken confirming successful publication.

• get_pubnub_messages: Fetches historical messages from one or more PubNub channels. Call this tool whenever you need to access past message history. Provide a list of channel names. Returns message content and metadata in JSON format.

• get_pubnub_presence: Retrieves real-time presence information for specified PubNub channels and channel groups. Call this tool when you need to monitor active users, occupancy counts, and subscriber UUIDs. Provide channel names and/or channel group names. Returns presence data in JSON format.

• write_pubnub_app: Generates step-by-step instructions for creating a PubNub application. Call this tool when you need a checklist of tasks such as setting up your PubNub account, creating a new app, and configuring settings.

服务配置

[{'mcpServers': {'pubnub': {'args': ['-y', '@pubnub/mcp'], 'command': 'npx', 'env': {'PUBNUB_PUBLISH_KEY': 'YOUR_PUBLISH_KEY', 'PUBNUB_SUBSCRIBE_KEY': 'YOUR_SUBSCRIBE_KEY'}}}}, {'mcpServers': {'pubnub': {'args': ['-y', '@pubnub/mcp'], 'command': 'npx', 'env': {'PUBNUB_PUBLISH_KEY': 'YOUR_PUBLISH_KEY', 'PUBNUB_SUBSCRIBE_KEY': 'YOUR_SUBSCRIBE_KEY'}}}}, {'mcpServers': {'pubnub': {'args': ['run', '-i', '-e', 'PUBNUB_PUBLISH_KEY', '-e', 'PUBNUB_SUBSCRIBE_KEY', 'pubnub/pubnub-mcp-server'], 'command': 'docker'}}}]

来源

• 来源：github
• 链接：https://github.com/stephenlb/pubnub-mcp-server