pubnub-mcp-server

pubnub-mcp-server

3.3
claude_codecurosrllmopenai_codexwindsurf

If you are the rightful owner of pubnub-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The PubNub Model Context Protocol (MCP) Server for Cursor IDE is a CLI-based server that enhances LLM-powered tools by providing access to PubNub SDK documentation and API resources.

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