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:

npx -y @pubnub/mcp

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:

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

Project Configuration

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

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

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:

export PUBNUB_PUBLISH_KEY=YOUR_PUBLISH_KEY
export PUBNUB_SUBSCRIBE_KEY=YOUR_SUBSCRIBE_KEY

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

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

• 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:

export PUBNUB_PUBLISH_KEY=YOUR_PUBLISH_KEY
export PUBNUB_SUBSCRIBE_KEY=YOUR_SUBSCRIBE_KEY
export HTTP_PORT=3000

Using NPX

# Start the MCP server in SSE mode on port 3000 with NPX
npx -y @pubnub/mcp

Using Docker

# Start the MCP server in SSE mode on port 3000 with Docker
docker run -i \
  -e PUBNUB_PUBLISH_KEY=$PUBNUB_PUBLISH_KEY \
  -e PUBNUB_SUBSCRIBE_KEY=$PUBNUB_SUBSCRIBE_KEY \
  -e HTTP_PORT=$HTTP_PORT \
  pubnub/pubnub-mcp-server

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

# Enable Chat SDK mode with NPX
npx -y @pubnub/mcp --chat-sdk

# Enable Chat SDK mode with Node.js directly
node index.js --chat-sdk

Cursor IDE Configuration

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

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

Project Configuration (.cursor/mcp.json):

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

Claude Code Integration

# Install Chat SDK mode MCP server
claude mcp add --scope user pubnub-chat -e PUBNUB_PUBLISH_KEY=your_publish_key -e PUBNUB_SUBSCRIBE_KEY=your_subscribe_key -- npx -y @pubnub/mcp --chat-sdk

Docker Usage

# Set environment variables
export PUBNUB_PUBLISH_KEY=your_publish_key
export PUBNUB_SUBSCRIBE_KEY=your_subscribe_key

# Run with Docker in Chat SDK mode
docker run -i \
  -e PUBNUB_PUBLISH_KEY=$PUBNUB_PUBLISH_KEY \
  -e PUBNUB_SUBSCRIBE_KEY=$PUBNUB_SUBSCRIBE_KEY \
  pubnub/pubnub-mcp-server --chat-sdk

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

# Subscribe and wait for one message (default behavior)
"Subscribe to the 'my_channel' channel and wait for one message"

# Collect multiple messages with timeout
"Subscribe to the 'notifications' channel and collect 5 messages with a 30-second timeout"

# Listen with timeout only
"Listen for messages on the 'alerts' channel for 10 seconds"

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

## Install the MCP server if you have node >= 18
claude mcp add --scope user pubnub -e PUBNUB_PUBLISH_KEY=your_publish_key -e PUBNUB_SUBSCRIBE_KEY=your_subscribe_key -- npx -y @pubnub/mcp

## Install the MCP server if you have node < 18 and need to point to the full path of node
claude mcp add --scope user 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

## Install the MCP server using Docker
# Ensure your PubNub keys are set as environment variables:
export PUBNUB_PUBLISH_KEY=your_publish_key
export PUBNUB_SUBSCRIBE_KEY=your_subscribe_key

# Depending on your machine’s CPU architecture, you may need to specify the target platform.
# For example:
#   docker run --platform linux/arm64 -i pubnub/pubnub-mcp-server
#   docker run --platform linux/amd64 -i pubnub/pubnub-mcp-server

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

And the output will be:

Added stdio MCP server pubnub with command: npx -y @pubnub/mcp to local config

Example prompt

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

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".

Remove the MCP server with:

claude mcp remove pubnub

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:

PUBNUB_PUBLISH_KEY=YOUR_PUBLISH_KEY \
PUBNUB_SUBSCRIBE_KEY=YOUR_SUBSCRIBE_KEY \
  node index.js

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

# 1) List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | node index.js

# 2) Read PubNub JavaScript SDK documentation
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":
  {"name":"read_pubnub_sdk_docs","arguments":{"language":"javascript"}}}' \
  | node index.js

# 3) Read PubNub Functions Resource docs (static Markdown)
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"read_pubnub_resources","arguments":{"document":"pubnub_functions"}}}' \
  | node index.js

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

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

2) Publish a message to a PubNub channel

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

Disabling PubNub Analytics Subscription

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

export MCP_SUBSCRIBE_ANALYTICS_DISABLED=true

Running All Tests

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

node test_all.js

Or via npm:

npm run test-all