by pubnub
Provides a CLI‑based server that exposes PubNub SDK documentation, API references, and real‑time messaging capabilities to LLM‑powered development environments via JSON‑RPC over STDIN/STDOUT.
A Model Context Protocol (MCP) server that makes PubNub SDK docs, conceptual guides, and PubNub real‑time features available as callable tools for AI agents in tools like Cursor, Claude Desktop, Claude Code, OpenAI Codex, and other LLM‑driven IDEs.
npx
command:
npx -y @pubnub/mcp
~/.cursor/mcp.json
(global) or .cursor/mcp.json
(project) file:
{
"mcpServers": {
"pubnub": {
"command": "npx",
"args": ["-y", "@pubnub/mcp"],
"env": {
"PUBNUB_PUBLISH_KEY": "YOUR_PUBLISH_KEY",
"PUBNUB_SUBSCRIBE_KEY": "YOUR_SUBSCRIBE_KEY"
}
}
}
}
HTTP_PORT
before launch.--chat-sdk
to focus solely on PubNub Chat SDK documentation and related tools.read_pubnub_sdk_docs
, publish_pubnub_message
, pubnub_subscribe_and_receive_messages
, get_pubnub_messages
, write_pubnub_app
, and manage_pubnub_account
through the MCP framework.@modelcontextprotocol/sdk
.write_pubnub_app
produces complete starter projects in JavaScript, Python, Go, etc.Q: Do I need a PubNub account to run the server? A: Only for operations that interact with live PubNub services (publish, subscribe, history, account management). Documentation tools work without keys.
Q: Which Node.js version is required? A: Node ≥ 18.
Q: Can I run the server on Windows?
A: Yes, as long as Node ≥ 18 and npx
are available.
Q: How do I enable SSE mode?
A: Export HTTP_PORT
(e.g., export HTTP_PORT=3000
) before starting the server.
Q: Is the server compatible with other IDEs besides Cursor? A: Any environment that can communicate over STDIN/STDOUT or HTTP (SSE) can use the server, including VS Code, Claude Desktop, and custom LLM integrations.
Q: How do I switch to Chat SDK mode?
A: Add --chat-sdk
to the launch command, e.g., npx -y @pubnub/mcp --chat-sdk
.
Q: Where are the static resources (guides, concepts) stored?
A: In the resources
directory of the repository and accessed via the read_pubnub_resources
tool.
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.json
If 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-server
npm:@pubnub/mcp
io.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>" } } } }
Discover more MCP servers with similar functionality and use cases
by zed-industries
Provides real-time collaborative editing powered by Rust, enabling developers to edit code instantly across machines with a responsive, GPU-accelerated UI.
by cline
Provides autonomous coding assistance directly in the IDE, enabling file creation, editing, terminal command execution, browser interactions, and tool extension with user approval at each step.
by continuedev
Provides continuous AI assistance across IDEs, terminals, and CI pipelines, offering agents, chat, inline editing, and autocomplete to accelerate software development.
by github
Enables AI agents, assistants, and chatbots to interact with GitHub via natural‑language commands, providing read‑write access to repositories, issues, pull requests, workflows, security data and team activity.
by block
Automates engineering tasks by installing, executing, editing, and testing code using any large language model, providing end‑to‑end project building, debugging, workflow orchestration, and external API interaction.
by RooCodeInc
An autonomous coding agent that lives inside VS Code, capable of generating, refactoring, debugging code, managing files, running terminal commands, controlling a browser, and adapting its behavior through custom modes and instructions.
by lastmile-ai
A lightweight, composable framework for building AI agents using Model Context Protocol and simple workflow patterns.
by firebase
Provides a command‑line interface to manage, test, and deploy Firebase projects, covering hosting, databases, authentication, cloud functions, extensions, and CI/CD workflows.
by gptme
Empowers large language models to act as personal AI assistants directly inside the terminal, providing capabilities such as code execution, file manipulation, web browsing, vision, and interactive tool usage.