io.github.pubnub/mcp-server

Official

by pubnub · TypeScript

PubNub MCP Server

PubNub Model Context Protocol MCP Server for Cursor and Claude

PubNub integration for real-time messaging and data synchronization.

Topics

claude-codecurosrllmmcpmcp-serveropenai-codexwindsurf

README.md18 KBView on GitHub

PubNub MCP Server

A hosted 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. Uses HTTP transport with OAuth authentication.

PubNub MCP Server

Features

📚 Comprehensive SDK Documentation - Access detailed documentation, code examples, and implementation guides for 20+ programming languages including JavaScript, Python, Java, Swift, Kotlin, C#, Ruby, Go, and more
🏗️ Application & Keyset Management - Create, configure, and manage PubNub applications and keysets with features like message persistence, file sharing, presence tracking, and app context
💬 Real-time Communication - Send and receive messages across channels, implement live chat, notifications, and real-time updates with support for both messages and lightweight signals
👥 User & Channel Management - Manage user profiles, channel metadata, and membership relationships with full CRUD operations for building community and social features. In addition, there is an option to view & manage user profiles, channels and memberships in PubNub Admin Portal (this requires Manage Premium).
📍 Presence & Activity Tracking - Monitor real-time user presence, see who's online in channels, and track user activity across your application
📊 Real-time Decisioning & Analytics - Trigger the right action when it matters, measure its impact, and adjust as conditions change -- all in real-time. Requires Illuminate.
📈 Channel, User & Message Analytics - Spot patterns in aggregated app activity, from top channels and country breakdowns to new vs. recurring users and device distribution, to understand engagement, usage, and performance. In addition, limited metrics are available for viewing in PubNub Admin Portal without Manage Premium; full analytics require Manage Premium.
🔍 Usage & Monitoring — Track billable usage across apps and keysets, review current and historical consumption, and export reports to understand cost drivers.
🔧 Multi-Platform Integration - Works with Cursor, Visual Studio Code, Claude Code, and other MCP-compatible AI assistants
⚡ Developer Experience - Built with TypeScript for type safety, includes testing infrastructure

Quick Start

The hosted server is managed by PubNub and provides the easiest way to get started — no installation required, and authentication is handled automatically via OAuth. If your AI tool doesn't support remote MCP servers, use the locally installed version (npx @pubnub/mcp@latest) instead.

Note: To switch to the hosted server (https://mcp.pubnub.com), remove the old local configuration from your AI client first, then follow the setup steps below.

Hosted PubNub MCP Server

Connect your AI assistant to https://mcp.pubnub.com — no installation required. Authentication is handled automatically via OAuth.

VS Code

Click the button above, then select Open in Visual Studio Code. Back in VS Code, click Install, then select the organization you want to authorize and click Allow access.

Alternatively, add the following to your VS Code settings.json manually:

json

{
  "mcp": {
    "servers": {
      "pubnub": {
        "url": "https://mcp.pubnub.com"
      }
    }
  }
}

Learn more in VS Code documentation

Cursor

Click the button above, then select Open Cursor. In Cursor, click Install, select the organization you want to authorize, and click Allow access. Navigate to Cursor Settings → Tools & MCP to verify PubNub is enabled.

Alternatively, add the following to .cursor/mcp.json (or ~/.cursor/mcp.json for global configuration) manually:

json

{
  "mcpServers": {
    "pubnub": {
      "url": "https://mcp.pubnub.com"
    }
  }
}

When you save the file, a notification is displayed. Click Enable to activate the MCP server. Learn more in Cursor documentation

Claude Code

In the terminal, run:

bash

claude mcp add --scope user --transport http pubnub https://mcp.pubnub.com

Then run claude to open Claude Code and enter /mcp. Select pubnub, then authenticate, and click Allow access to complete authorization. Learn more in Claude Code documentation

Claude Desktop

Note: The following instructions apply to Pro and Max plans. For Enterprise plans, the setup is configured by your organization administrator. Refer to Anthropic's documentation for details.

In Claude Desktop, navigate to Customize → Connectors.
Click + and select Add custom connector.
Enter https://mcp.pubnub.com as the connector URL.
Complete the OAuth login when prompted.

Learn more in Claude Desktop documentation

Codex

In the terminal, run:

bash

codex mcp add pubnub --url https://mcp.pubnub.com

Then run codex mcp login pubnub to authenticate, select the organization you want to authorize, and click Allow access. Learn more in Codex documentation

Codex Desktop

Navigate to Settings → MCP servers and click + Add server.
Select Streamable HTTP as the transport type.
Enter https://mcp.pubnub.com as the server URL.
Follow the OAuth login prompt to complete authorization.

Learn more in Codex Desktop documentation

Gemini CLI

In the terminal, run:

bash

gemini mcp add pubnub --scope user --transport http https://mcp.pubnub.com

Then run gemini to open Gemini CLI and run /mcp auth pubnub to authenticate. Learn more in Gemini CLI documentation

OpenCode

Add the following to ~/.config/opencode/config.json:

json

{
  "mcp": {
    "pubnub": {
      "type": "remote",
      "url": "https://mcp.pubnub.com",
      "enabled": true
    }
  }
}

Then run opencode mcp auth pubnub to authenticate. Learn more in OpenCode documentation

Local PubNub MCP Server

If your AI tool doesn't support remote MCP servers, run the server locally with:

bash

npx @pubnub/mcp@latest

API Key

Before you begin, we highly recommend creating a Service Integration in the PubNub Admin Portal and providing your API key to the MCP server. While some basic features will work without it, adding an API key unlocks much more functionality. Alternatively, refer to Local server configuration for instructions on configuring the server to work with a single PubNub keyset.

The installation process for an MCP server depends on the AI assistant you're using. For the standard setup, you'll need Node.js (v20.0.0 or higher).

VS Code

Just click the link above, then select "Open in Visual Studio Code" on the page that appears. Back in VS Code, click "Install". You'll be prompted to enter your PubNub API Key. Once provided, your MCP server is ready to use. For additional configuration options, refer to Local server configuration.

Cursor

Click the link above, then select "Open Cursor" on the page that appears. Back in Cursor, there's a "Install MCP Server?" prompt. Make sure to provide the value for variable holding your PubNub API Key. Once you do, click "Install". Your MCP server is now ready to use. For additional configuration options, refer to Local server configuration.

Claude Code

With Claude Code installed run this command to have the MCP added to your configuration. Make sure to replace the value of <your-api-key>:

bash

claude mcp add pubnub --env PUBNUB_API_KEY=<your-api-key> --scope user --transport stdio -- npx -y @pubnub/mcp@latest

Server is added in the "User" scope which means it will be available across all projects. For additional configuration options, refer to Local server configuration.

Codex

With Codex installed run this command to have the MCP added to your configuration. Make sure to replace the value of <your-api-key>:

bash

codex mcp add pubnub --env PUBNUB_API_KEY=<your-api-key> -- npx -y @pubnub/mcp@latest

For additional configuration options, refer to Local server configuration.

Gemini CLI

Gemini CLI does not support automatic MCP installations. You'll have to manually edit your settings.json file and add the section below. Make sure to replace the value of <your-api-key>:

json

"mcpServers": {
  "pubnub": {
    "command": "npx",
    "args": [
      "-y",
      "@pubnub/mcp@latest"
    ],
    "env": {
      "PUBNUB_API_KEY": "<your-api-key>"
    }
  }
}

For additional configuration options, refer to the Local server configuration section in the PubNub documentation.

Development

Prerequisites

Node.js >= 20.0.0

Running locally

bash

npm install
npm run dev

Environment variables

Variable	Description	Required
`PORT`	HTTP server port (default: 3000)	No
`MCP_OAUTH_ENABLED`	Enable OAuth authentication	Yes (for production)
`OAUTH_ISSUER`	OAuth authorization server URL	When OAuth enabled
`OAUTH_CLIENT_ID`	OAuth client ID	When OAuth enabled
`OAUTH_CLIENT_SECRET`	OAuth client secret	When OAuth enabled
`ADMIN_API_RESOURCE_URL`	Admin API resource identifier	When OAuth enabled
`MCP_RESOURCE_URL`	MCP resource URL	When OAuth enabled
`MCP_CLOUD_MODE`	Cloud deployment mode	No
`MCP_SESSION_SUPPORT`	Enable session persistence	No
`ADMIN_API_V2_URL`	Override Admin API v2 endpoint	No
`PUBNUB_ORIGIN`	Override PubNub origin	No
`SDK_DOCS_API_URL`	Override docs API endpoint	No

Testing

bash

npm run test:unit        # Unit tests
npm run test:integration # Integration tests (requires build)
npm run test:coverage    # Coverage report

API Reference

This PubNub MCP server provides a comprehensive set of tools, resources, and prompts to help you build real-time applications. Below is a complete reference of all available functionality:

Tools

Documentation Access

get_sdk_documentation - Get PubNub Core SDK documentation for specific programming languages and features
get_chat_sdk_documentation - Get PubNub Chat SDK documentation for specific programming languages and features
how_to - Get PubNub conceptual guides for specific use cases and integrations
write_pubnub_app - Get PubNub best practices guide covering architecture, security, channel modeling, and optimization
get_sdk_migration_guide - Get SDK version migration guides
get_general_migration_guide - Get general platform migration guides

App & Keyset Management

manage_apps - Manage PubNub apps (list, create, update)
manage_keysets - Manage PubNub keysets (get, list, create, update)
get_usage_metrics - Fetch usage metrics for an account, app, or keyset

Real-time Communication

send_pubnub_message - Send messages or lightweight signals to PubNub channels in real-time
subscribe_and_receive_pubnub_messages - Subscribe to channels and receive real-time messages with configurable timeout and message limits
get_pubnub_messages - Fetch historical messages from one or more PubNub channels
get_pubnub_presence - Get presence data using HereNow (channel occupancy) or WhereNow (user's channels)
manage_app_context - Manage PubNub App Context (Objects API) for users, channels, and memberships with full CRUD operations

Illuminate Analytics & Automation

manage_illuminate - Manage PubNub Illuminate resources (business objects, queries, metrics, decisions, dashboards) with full CRUD, activation, analytics queries, action log inspection, and test data publishing

Insights Analytics

insights - Query PubNub Insights for aggregated analytics metrics: unique channels/users, message volume, top-N rankings (channels, users, message types), country breakdowns, new vs. recurring user trends, user duration, and device type distributions. Requires a Service Integration API key with Account-level Insights Read access and Insights Premium tier.

Prompts

Healthcare & HIPAA Compliance

hipaa-chat-short - Quick prompt to create HIPAA compliant chat applications
hipaa-chat-long - Detailed prompt for HIPAA compliant chat with Pub/Sub, Presence, and App Context

React Development

react-app-short - Scaffold a React app with PubNub Pub/Sub and Presence
react-app-long - Comprehensive React app with real-time messaging, presence indicators, and user metadata

Gaming Applications

gamelobby-short - Build multiplayer game lobby with chat and presence
gamelobby-long - Advanced multiplayer lobby with team assignments and real-time features

OEM & Multi-Tenant Solutions

oem-client-management - Create apps and configure keysets for OEM client deployments
multi-tenant-onboarding-short - Implement automated tenant onboarding for SaaS applications
multi-tenant-onboarding-long - Enterprise-grade multi-tenant onboarding with data isolation and error handling

Illuminate Analytics & Automation

illuminate-spam-detection - Set up an Illuminate spam detection pipeline with escalating moderation actions
illuminate-reward-engagement - Build an Illuminate engagement reward pipeline for live events and gaming
illuminate-use-case - Guided setup of any Illuminate analytics and automation use case
illuminate-test-verify - Test and verify an existing Illuminate configuration end-to-end

Insights Analytics

insights-snapshot - Quick high-level analytics snapshot for a date range: unique channels, unique users, message volume, top 20 channels by messages, and anomaly callouts
insights-channel-analysis - Deep dive into top channels by ranking category, channel naming patterns, and cross-category engagement comparisons
insights-user-growth - New vs. recurring user trends, daily/weekly/monthly breakdowns, top countries, and whale user identification
insights-engagement-deep-dive - Average user duration, session-length bucket histogram, top channels by user-minutes, and device-type breakdown across publishes, subscribers, and unique users

Resources

pubnub_sdk_docs - Access PubNub SDK documentation via URI scheme: pubnub-docs://sdk/{language}/{feature}

Supported languages: asyncio, c-core, c-sharp, dart, freertos, go, java, javascript, kotlin, mbed, objective-c, php, posix-c, posix-cpp, python, ruby, rust, swift, unity, unreal, windows-c, windows-cpp

Supported features: access-manager, access-manager-v2, channel-groups, configuration, encryption, files, message-actions, misc, mobile-push, objects, presence, publish-and-subscribe, storage-and-playback

pubnub_chat_sdk_docs - Access PubNub Chat SDK documentation via URI scheme: pubnub-docs://chat-sdk/{language}/{feature}

Supported Languages: javascript, kotlin, swift, unity, unreal

Supported Features: channels-create, channels-delete, channels-details, channels-invite, channels-join, channels-leave, channels-list, channels-membership, channels-references, channels-typing-indicator, channels-updates, channels-watch, connection-management, custom-events, error-logging, messages-delete, messages-details, messages-drafts, messages-files, messages-forward, messages-history, messages-links, messages-moderation, messages-pinned, messages-quotes, messages-reactions, messages-read-receipts, messages-restore, messages-send-receive, messages-threads, messages-unread, messages-updates, moderation, push-notifications, users-create, users-delete, users-details, users-list, users-mentions, users-moderation, users-moderation-user, users-permissions, users-presence, users-updates, utility-methods

Install

Configuration

Environment variables

PUBNUB_API_KEYsecret

Your PubNub API Key. Required for all operations related to your account/keyset

PUBNUB_PUBLISH_KEYsecret

Optional PubNub publish key for real-time operations

PUBNUB_SUBSCRIBE_KEYsecret

Optional PubNub subscribe key for real-time operations

PUBNUB_USER_ID

Optional variable that can be provided to change the User ID for the SDK (real-time) operations (default: pubnub-mcp)

PUBNUB_EMAIL

(Deprecated - use API Key instead) Your PubNub account email. Required for all operations related to your account/keyset

PUBNUB_PASSWORDsecret

(Deprecated - use API Key instead) Your PubNub account password. Required for all operations related to your account/keyset

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@pubnub/mcp@2.3.2"
      ],
      "env": {
        "PUBNUB_API_KEY": "<YOUR_PUBNUB_API_KEY>",
        "PUBNUB_PUBLISH_KEY": "<YOUR_PUBNUB_PUBLISH_KEY>",
        "PUBNUB_SUBSCRIBE_KEY": "<YOUR_PUBNUB_SUBSCRIBE_KEY>",
        "PUBNUB_USER_ID": "<YOUR_PUBNUB_USER_ID>",
        "PUBNUB_EMAIL": "<YOUR_PUBNUB_EMAIL>",
        "PUBNUB_PASSWORD": "<YOUR_PUBNUB_PASSWORD>"
      }
    }
  }
}