PubNub MCP Server

PubNub Model Context Protocol (MCP) Server for Cursor IDE

This repository provides a CLI-based Model Context Protocol (MCP) server that exposes PubNub SDK documentation and PubNub API resources to LLM-powered tools. This improves the LLM AI Agent's ability to understand and interact with PubNub's SDKs and APIs.

Features

• MCP server exposing tools for interacting with PubNub via JSON-RPC over STDIN/STDOUT.
• MCP server supports SSE Mode by supplying HTTP_PORT environment variable.
• Retrieve official PubNub SDK documentation (HTML → Markdown) for:
  • Languages: JavaScript, Python, Java, Go, Ruby, Swift, Objective-C, C#, PHP, Rust, Unity, Kotlin, Unreal.
  • API reference sections: configuration, publish-and-subscribe, presence, access-manager, channel-groups, storage-and-playback, mobile-push, objects, files, message-actions, misc, functions.
• Retrieve official PubNub Chat SDK documentation (HTML → Markdown) for:
  • Chat SDK languages: JavaScript, Kotlin, Swift, Unity, Unreal.
  • Chat SDK topics: configuration, chat, channel, user, message, membership, thread-channel, thread-message, message-draft, event, access-control, glossary.
• Fetch PubNub conceptual guides and how-to documentation from local markdown files in the resources directory (e.g., pubnub_concepts, pubnub_features, pubnub_security, how_to_send_receive_json, how_to_encrypt_messages_files, etc.).
• Publish messages to PubNub channels with publish_pubnub_message, returning a timetoken.
• Subscribe to channels and receive real-time messages with pubnub_subscribe_and_receive_messages, supporting single or multiple message collection with optional timeout.
• Fetch historical messages from one or more channels with get_pubnub_messages, returning message content and metadata in JSON.
• Retrieve real-time presence information (occupancy counts, subscriber UUIDs) for channels and channel groups with get_pubnub_presence.
• Generate step-by-step instructions for creating a PubNub application, including code snippets for initializing the PubNub SDK in multiple languages using write_pubnub_app.
• Manage PubNub account apps and API keys with manage_pubnub_account, supporting create, list, and delete operations for both apps and API keys.
• Environment variable configuration: supports PUBNUB_PUBLISH_KEY and PUBNUB_SUBSCRIBE_KEY for authenticating SDK operations.
• Converts remote HTML articles to Markdown using jsdom and turndown for consistent documentation formatting.
• Input validation via Zod schemas for all tool parameters, ensuring robust error handling.
• Extensible tool definitions leveraging the Model Context Protocol SDK (@modelcontextprotocol/sdk) with McpServer and StdioServerTransport.

Example Prompts

• "Write a PubNub app that lets the user watch streaming videos with built-in multi-user chat with PubNub."
• "Write a PubNub app for on-demand delivery of groceries with a map."
• "Write a PubNub app that tracks the location of a package in real-time."
• "Write a PubNub app that shows the weather forecast in real-time."
• "Write a PubNub app that lets users play multiplayer games with friends."
• "Write a PubNub app that shows live stock prices and news updates."
• "Write a PubNub app that lets users create and share playlists with friends."
• "Build a PubNub JavaScript app that subscribes to the my_channel channel and logs messages to the console."
• "Publish a message to the my_channel channel with the message Hello, PubNub!."
• "Subscribe to the my_channel channel and wait for one message."
• "Subscribe to the notifications channel and collect 5 messages with a 30-second timeout."
• "Listen for messages on the alerts channel for 10 seconds."
• "Show me the PubNub JavaScript SDK documentation for subscribe()."
• "List all available PubNub Functions."
• "Fetch the Python SDK docs for the publish() method."
• "Fetch the message history for the test channel."
• "Retrieve presence information (occupancy and UUIDs) for the test channel and the default channel group."
• "List all my PubNub apps."
• "List all API keys across my PubNub account."
• "Create a new PubNub app."
• "Create a new API key in my PubNub account."
• "Delete test apps from my PubNub account."
• "Delete test API keys from my PubNub account."

This requires Node.js (>= 18) and npm (https://nodejs.org/). npx will automatically fetch and run the latest MCP server.

Prerequisites

• Node.js (>= 18) and npm
• Cursor IDE with MCP support
• (Optional) PubNub account and API keys for live examples

Installation

The preferred way to run the PubNub MCP server locally or add it to Cursor IDE via npx:

Configuration

Cursor must be in AGENT MODE to use MCP servers.

Cursor IDE discovers MCP servers via a JSON config file. Configure the PubNub MCP server globally or per project.

Global Configuration

Edit or create ~/.cursor/mcp.json:

Project Configuration

In your project directory, create .cursor/mcp.json:

Environment Variables

The PubNub MCP server supports the following environment variables:

• PUBNUB_PUBLISH_KEY: Your PubNub publish key (required for publishing messages)
• PUBNUB_SUBSCRIBE_KEY: Your PubNub subscribe key (required for subscribing and message history)

Docker-Based Configuration

If you prefer to run the MCP server via Docker, set your PubNub keys as environment variables:

Then configure your ~/.cursor/mcp.json (or .cursor/mcp.json in your project):

• command specifies the executable to launch the MCP server.
• args specifies the arguments to pass to the command.
• env sets environment variables for the server process.

SSE Mode

To enable Server-Sent Events (SSE) HTTP transport, export the HTTP_PORT environment variable and start the MCP server. Ensure your PubNub API keys are set in the environment:

Using NPX

Using Docker

Chat SDK Mode

The PubNub MCP server supports a specialized Chat SDK Mode that focuses exclusively on PubNub Chat SDK documentation and functionality. When enabled with the --chat-sdk flag, the server provides streamlined access to Chat SDK resources while excluding general PubNub SDK tools.

Key Features

• Focused Chat SDK Documentation: Access official PubNub Chat SDK docs for JavaScript, Kotlin, Swift, Unity, and Unreal
• Chat-Specific Topics: Configuration, chat, channel, user, message, membership, thread-channel, thread-message, message-draft, event, access-control, and glossary
• Streamlined Tool Set: Excludes general PubNub tools to reduce complexity and focus on Chat SDK functionality
• Same Real-Time Capabilities: Retains message publishing, subscription, history, and presence tools

Usage

Command Line

Cursor IDE Configuration

Global Configuration (~/.cursor/mcp.json):

Project Configuration (.cursor/mcp.json):

Claude Code Integration

Docker Usage

Available Tools in Chat SDK Mode

Included Tools:

• read_pubnub_chat_sdk_docs - Access Chat SDK documentation for specific languages and topics
• publish_pubnub_message - Publish messages to PubNub channels
• get_pubnub_messages - Fetch historical messages from channels
• get_pubnub_presence - Retrieve real-time presence information
• pubnub_subscribe_and_receive_messages - Subscribe and receive real-time messages

Excluded Tools:

• read_pubnub_sdk_docs - General PubNub SDK documentation
• write_pubnub_app - PubNub app templates and setup instructions
• read_pubnub_resources - General PubNub conceptual guides
• manage_pubnub_account - PubNub account management

Example Chat SDK Prompts

• "Show me the JavaScript Chat SDK documentation for user management"
• "Get the Swift Chat SDK configuration documentation"
• "How do I implement threaded messaging with the Kotlin Chat SDK?"
• "Show me the Unity Chat SDK documentation for message handling"
• "Explain channel management in the Unreal Chat SDK"
• "Get Chat SDK documentation for implementing access control"
• "Show me how to handle message drafts in the JavaScript Chat SDK"
• "What are the membership features available in the Chat SDK?"

Using in Cursor IDE

1. Restart Cursor IDE or open a new session.
2. Open the MCP settings pane and verify the pubnub server is listed under Available Tools & Resources.
3. In chat, invoke available resources:
   • pubnub://docs/javascript — Fetch PubNub JavaScript SDK documentation
   • pubnub://docs/python — Fetch PubNub Python SDK documentation
   • pubnub://docs/java — Fetch PubNub Java SDK documentation
   • pubnub://functions — List PubNub Functions (static content from resources/pubnub_functions.md)
4. Approve resource execution when prompted, or enable auto-run in settings for trusted resources.

Real-Time Message Subscription

The pubnub_subscribe_and_receive_messages tool provides real-time message listening capabilities, allowing you to subscribe to PubNub channels and receive messages as they're published. This tool automatically handles subscription lifecycle, message collection, and cleanup.

Key Features

• Flexible Message Collection: Wait for a single message (default) or specify how many messages to collect
• Timeout Support: Set optional timeouts to prevent indefinite waiting
• Automatic Cleanup: Automatically unsubscribes and cleans up listeners after receiving the specified number of messages or timeout
• Structured Response: Returns detailed message information including channel, content, publisher, and timetoken

Usage Examples

Parameters

• channel (required): Name of the PubNub channel to subscribe to
• messageCount (optional, default: 1): Number of messages to wait for before unsubscribing
• timeout (optional): Timeout in milliseconds to avoid waiting indefinitely

Response Format

The tool returns a JSON object containing:

• channel: The subscribed channel name
• messageCount: Number of messages actually received
• messages: Array of message objects with channel, message content, publisher, timetoken, and subscription info

Claude Code

And the output will be:

Example prompt

Remove the MCP server with:

Using VS Code

To install the PubNub MCP Server in VS Code:

Prerequisites

• VS Code with GitHub Copilot installed and logged in
• Node.js (>= 18) and npm
• A workspace opened in VS Code

Installation Steps

1. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
2. Type MCP and select MCP: Add Server
3. Choose NPM package when prompted
4. Enter @pubnub/mcp as the package name
5. VS Code will install the package and automatically open the mcp.json configuration file
6. Add your PubNub Publish and Subscribe keys to the configuration:

7. Save the mcp.json file
8. Restart VS Code or reload the window to activate the MCP server

The PubNub MCP server will now be available in VS Code with GitHub Copilot, providing access to PubNub SDK documentation and real-time messaging capabilities.

Using Claude Desktop

If you prefer the Docker-based MCP server in Claude Desktop:

1. Ensure your PubNub keys are exported in your shell:
   export PUBNUB_PUBLISH_KEY=your_publish_key export PUBNUB_SUBSCRIBE_KEY=your_subscribe_key
2. In the Tools section of Claude Desktop, add a new tool named pubnub.
3. Set the Command to docker.
4. Set Arguments to:
   [ "run", "-i", "-e", "PUBNUB_PUBLISH_KEY", "-e", "PUBNUB_SUBSCRIBE_KEY", "pubnub/pubnub-mcp-server" ]

Note: On some machines (e.g., Apple Silicon), you may need to specify the Docker platform. Insert --platform linux/arm64 (or --platform linux/amd64) immediately after "run" in the Arguments array. For example:

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

5. Save the configuration.

Claude Desktop will invoke the PubNub MCP server container via Docker.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Troubleshooting

• Must be in agent mode to use MCP servers.
• Verify Node.js and npm installation.
• Ensure index.js has execute permission.
• Check that the command, args, and env settings are correct.
• Review Cursor IDE logs for MCP startup errors.

Direct JSON-RPC Command-Line Usage

You can invoke the MCP server directly over STDIN/STDOUT using JSON-RPC v2.0. Ensure your PubNub keys are set in the environment, for example:

Once the server is running (or using a one-off invocation), send requests by piping JSON into node index.js. Examples:

Quick JSON-RPC Examples

Below are simplified JSON-RPC v2.0 command-line examples using STDIN/STDOUT to fetch PubNub SDK documentation and publish messages.

1) Fetch PubNub JavaScript SDK documentation

2) Publish a message to a PubNub channel

Disabling PubNub Analytics Subscription

To disable the PubNub server analytics subscription, set the following environment variable:

Running All Tests

You can run the complete test suite (unit tests, SSE tests, model tooling tests, and benchmarks) with:

Or via npm: