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.

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

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

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

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

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

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:

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.

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.

Claude Code

And the output will be:

Example prompt

Remove the MCP server with:

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