by pubnub
Provides a CLI‑based server that exposes PubNub SDK documentation, API references, and real‑time messaging tools to LLM‑powered development environments via JSON‑RPC over STDIN/STDOUT.
The server delivers PubNub SDK docs, API resources, and messaging operations to AI‑assisted coding assistants (Cursor, Claude Desktop, Claude Code, OpenAI Codex, etc.). It runs as a lightweight CLI process that speaks the Model Context Protocol, enabling tools to request documentation, publish/subscribe to channels, fetch history, manage accounts, and more.
npx -y @pubnub/mcp (or via Docker).\PUBNUB_PUBLISH_KEY and PUBNUB_SUBSCRIBE_KEY in the environment or in the Cursor/VS Code mcp.json configuration.\my_channel channel”) or send JSON‑RPC requests directly over STDIN/STDOUT.HTTP_PORT.\@modelcontextprotocol/sdk with McpServer and StdioServerTransport.\write_pubnub_app) directly in the IDE.\Q: Do I need a PubNub account to use the server? A: Yes, for any operation that accesses live PubNub services (publish, subscribe, history, account management) you must provide a valid publish and subscribe key.
Q: Can I run the server without Node.js?
A: The primary distribution is a Node.js package; however, a Docker image (pubnub/pubnub-mcp-server) is available for environments without Node.
Q: How do I enable Server‑Sent Events?
A: Export HTTP_PORT before starting the server; the MCP server will listen on that port and expose an SSE endpoint.
Q: What if I only need Chat SDK documentation?
A: Start the server with the --chat-sdk flag (e.g., npx -y @pubnub/mcp --chat-sdk) to load the trimmed toolset.
Q: Is the server compatible with other IDEs besides Cursor? A: Yes. It works with any tool that supports the Model Context Protocol, such as Claude Desktop/Code, VS Code extensions, or custom JSON‑RPC clients.

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.

HTTP_PORT environment variable.resources directory (e.g., pubnub_concepts, pubnub_features, pubnub_security, how_to_send_receive_json, how_to_encrypt_messages_files, etc.).publish_pubnub_message, returning a timetoken.pubnub_subscribe_and_receive_messages, supporting single or multiple message collection with optional timeout.get_pubnub_messages, returning message content and metadata in JSON.get_pubnub_presence.write_pubnub_app.manage_pubnub_account, supporting create, list, and delete operations for both apps and API keys.PUBNUB_PUBLISH_KEY and PUBNUB_SUBSCRIBE_KEY for authenticating SDK operations.jsdom and turndown for consistent documentation formatting.@modelcontextprotocol/sdk) with McpServer and StdioServerTransport.my_channel channel and logs messages to the console."my_channel channel with the message Hello, PubNub!."my_channel channel and wait for one message."notifications channel and collect 5 messages with a 30-second timeout."alerts channel for 10 seconds."subscribe()."publish() method."test channel."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.
The preferred way to run the PubNub MCP server locally or add it to Cursor IDE via npx:
npx -y @pubnub/mcp
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.
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"
}
}
}
}
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"
}
}
}
}
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)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.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
# Start the MCP server in SSE mode on port 3000 with NPX
npx -y @pubnub/mcp
# 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
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.
# 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
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"
}
}
}
}
# 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
# 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
Included Tools:
read_pubnub_chat_sdk_docs - Access Chat SDK documentation for specific languages and topicspublish_pubnub_message - Publish messages to PubNub channelsget_pubnub_messages - Fetch historical messages from channelsget_pubnub_presence - Retrieve real-time presence informationpubnub_subscribe_and_receive_messages - Subscribe and receive real-time messagesExcluded Tools:
read_pubnub_sdk_docs - General PubNub SDK documentationwrite_pubnub_app - PubNub app templates and setup instructionsread_pubnub_resources - General PubNub conceptual guidesmanage_pubnub_account - PubNub account managementpubnub://docs/javascript — Fetch PubNub JavaScript SDK documentationpubnub://docs/python — Fetch PubNub Python SDK documentationpubnub://docs/java — Fetch PubNub Java SDK documentationpubnub://functions — List PubNub Functions (static content from resources/pubnub_functions.md)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.
# 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"
channel (required): Name of the PubNub channel to subscribe tomessageCount (optional, default: 1): Number of messages to wait for before unsubscribingtimeout (optional): Timeout in milliseconds to avoid waiting indefinitelyThe tool returns a JSON object containing:
channel: The subscribed channel namemessageCount: Number of messages actually receivedmessages: Array of message objects with channel, message content, publisher, timetoken, and subscription info## 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
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
To install the PubNub MCP Server in VS Code:
Ctrl+Shift+P or Cmd+Shift+P)MCP and select MCP: Add Server@pubnub/mcp as the package namemcp.json configuration file{
"mcpServers": {
"@pubnub/mcp": {
"command": "npx",
"args": ["-y", "@pubnub/mcp"],
"env": {
"PUBNUB_PUBLISH_KEY": "YOUR_PUBLISH_KEY",
"PUBNUB_SUBSCRIBE_KEY": "YOUR_SUBSCRIBE_KEY"
}
}
}
}
mcp.json fileThe PubNub MCP server will now be available in VS Code with GitHub Copilot, providing access to PubNub SDK documentation and real-time messaging capabilities.
If you prefer the Docker-based MCP server in Claude Desktop:
export PUBNUB_PUBLISH_KEY=your_publish_key
export PUBNUB_SUBSCRIBE_KEY=your_subscribe_key
docker.[
"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" ]
Claude Desktop will invoke the PubNub MCP server container via Docker.
This project is licensed under the MIT License. See the LICENSE file for details.
index.js has execute permission.command, args, and env settings are correct.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
Below are simplified JSON-RPC v2.0 command-line examples using STDIN/STDOUT to fetch PubNub SDK documentation and publish messages.
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"read_pubnub_sdk_docs","arguments":{"language":"javascript"}}}' | node index.js
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
To disable the PubNub server analytics subscription, set the following environment variable:
export MCP_SUBSCRIBE_ANALYTICS_DISABLED=true
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
This server is automatically published to the MCP Registry when new versions are released. The publishing process uses GitHub Actions for automated CI/CD.
The repository includes automated publishing configuration:
server.json - MCP registry configuration file.github/workflows/publish-mcp.yml - GitHub Actions workflow for automated publishingNPM Token: Add NPM_TOKEN as a secret in your GitHub repository:
NPM_TOKEN with your npm publishing tokenVersion Management: Ensure package.json version is properly maintained
To publish a new version to both npm and the MCP Registry:
# Update version (patch, minor, or major)
npm version patch
# Push changes and tags to trigger automated publishing
git push origin main
git push origin --tags
When you push a version tag (e.g., v1.0.98), the GitHub Actions workflow automatically:
@pubnub/mcp)package.json and server.jsonIf you need to publish manually:
# Install the MCP Publisher CLI
curl -fsSL https://registry.modelcontextprotocol.io/install.sh | bash
# Login using GitHub authentication (for io.github.pubnub.* namespace)
mcp-publisher login github
# Publish to the MCP Registry
mcp-publisher publish
io.github.pubnub.mcp-servernpm:@pubnub/mcpio.github.pubnub.* (GitHub-authenticated)Please log in to share your review and rating for this MCP.
{
"mcpServers": {
"pubnub": {
"command": "npx",
"args": [
"-y",
"@pubnub/mcp"
],
"env": {
"PUBNUB_PUBLISH_KEY": "<YOUR_PUBLISH_KEY>",
"PUBNUB_SUBSCRIBE_KEY": "<YOUR_SUBSCRIBE_KEY>"
}
}
}
}claude mcp add pubnub npx -y @pubnub/mcpExplore related MCPs that share similar capabilities and solve comparable challenges
by zed-industries
A high‑performance, multiplayer code editor designed for speed and collaboration.
by modelcontextprotocol
Model Context Protocol Servers
by modelcontextprotocol
A Model Context Protocol server for Git repository interaction and automation.
by modelcontextprotocol
A Model Context Protocol server that provides time and timezone conversion capabilities.
by cline
An autonomous coding assistant that can create and edit files, execute terminal commands, and interact with a browser directly from your IDE, operating step‑by‑step with explicit user permission.
by continuedev
Enables faster shipping of code by integrating continuous AI agents across IDEs, terminals, and CI pipelines, offering chat, edit, autocomplete, and customizable agent workflows.
by upstash
Provides up-to-date, version‑specific library documentation and code examples directly inside LLM prompts, eliminating outdated information and hallucinated APIs.
by github
Connects AI tools directly to GitHub, enabling natural‑language interactions for repository browsing, issue and pull‑request management, CI/CD monitoring, code‑security analysis, and team collaboration.
by daytonaio
Provides a secure, elastic infrastructure that creates isolated sandboxes for running AI‑generated code with sub‑90 ms startup, unlimited persistence, and OCI/Docker compatibility.