@crashbytes/pusher-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CrashBytes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# Pusher Channels MCP Server
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that gives AI agents the ability to send realtime messages, query channels, and manage users through [Pusher Channels](https://pusher.com/channels).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `trigger_event` | Send an event to one or more channels |
+| `trigger_batch_events` | Send up to 10 events in a single API call |
+| `list_channels` | List active channels with optional prefix filter |
+| `get_channel_info` | Get subscription/user count for a channel |
+| `get_presence_users` | List users connected to a presence channel |
+| `authorize_channel` | Generate auth tokens for private/presence channels |
+| `terminate_user_connections` | Disconnect all connections for a user |
+
+## Prerequisites
+
+- Node.js 18 or later
+- A [Pusher Channels](https://pusher.com) account (free tier available)
+
+## Installation
+
+```bash
+npm install -g @crashbytes/pusher-mcp-server
+```
+
+Or clone and build from source:
+
+```bash
+git clone https://github.com/CrashBytes/pusher-mcp-server.git
+cd pusher-mcp-server
+npm install
+npm run build
+```
+
+## Configuration
+
+You need four environment variables from your [Pusher dashboard](https://dashboard.pusher.com):
+
+| Variable | Description |
+|----------|-------------|
+| `PUSHER_APP_ID` | Your Pusher app ID |
+| `PUSHER_KEY` | Your Pusher app key |
+| `PUSHER_SECRET` | Your Pusher app secret |
+| `PUSHER_CLUSTER` | Your Pusher cluster (e.g. `us2`, `eu`, `ap1`) |
+
+## Usage with Claude Desktop
+
+Add the following to your Claude Desktop config file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "pusher": {
+      "command": "node",
+      "args": ["/path/to/pusher-mcp-server/build/index.js"],
+      "env": {
+        "PUSHER_APP_ID": "your_app_id",
+        "PUSHER_KEY": "your_app_key",
+        "PUSHER_SECRET": "your_app_secret",
+        "PUSHER_CLUSTER": "us2"
+      }
+    }
+  }
+}
+```
+
+If installed globally via npm:
+
+```json
+{
+  "mcpServers": {
+    "pusher": {
+      "command": "pusher-mcp-server",
+      "env": {
+        "PUSHER_APP_ID": "your_app_id",
+        "PUSHER_KEY": "your_app_key",
+        "PUSHER_SECRET": "your_app_secret",
+        "PUSHER_CLUSTER": "us2"
+      }
+    }
+  }
+}
+```
+
+## Usage with Claude Code
+
+```bash
+claude mcp add pusher -- node /path/to/pusher-mcp-server/build/index.js
+```
+
+Set the environment variables in your shell before running, or configure them in your Claude Code MCP settings.
+
+## Example Prompts
+
+Once configured, you can ask Claude things like:
+
+- "Send a 'deploy-complete' event to the notifications channel with the message 'v2.1.0 deployed'"
+- "Show me all active presence channels"
+- "How many users are on the presence-lobby channel?"
+- "Disconnect user abc123 from all channels"
+
+## Development
+
+```bash
+npm install
+npm run dev          # Run with tsx (hot reload)
+npm run build        # Compile TypeScript
+npm run type-check   # Check types without emitting
+```
+
+## Tutorial
+
+For a step-by-step guide on building this server from scratch, see the full tutorial on [CrashBytes](https://crashbytes.com/tutorials/building-pusher-channels-mcp-server-realtime-ai-2026).
+
+## License
+
+MIT

package/build/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTriggerEvent } from "./tools/trigger-event.js";
+import { registerTriggerBatchEvents } from "./tools/trigger-batch-events.js";
+import { registerListChannels } from "./tools/list-channels.js";
+import { registerGetChannelInfo } from "./tools/get-channel-info.js";
+import { registerGetPresenceUsers } from "./tools/get-presence-users.js";
+import { registerAuthorizeChannel } from "./tools/authorize-channel.js";
+import { registerTerminateUser } from "./tools/terminate-user.js";
+const server = new McpServer({
+    name: "pusher-channels",
+    version: "1.0.0",
+});
+// Register all tools
+registerTriggerEvent(server);
+registerTriggerBatchEvents(server);
+registerListChannels(server);
+registerGetChannelInfo(server);
+registerGetPresenceUsers(server);
+registerAuthorizeChannel(server);
+registerTerminateUser(server);
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Pusher MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/build/pusher-client.js

@@ -0,0 +1,32 @@
+// src/pusher-client.ts
+import Pusher from "pusher";
+let client = null;
+export function getPusherClient() {
+    if (client)
+        return client;
+    const appId = process.env.PUSHER_APP_ID;
+    const key = process.env.PUSHER_KEY;
+    const secret = process.env.PUSHER_SECRET;
+    const cluster = process.env.PUSHER_CLUSTER;
+    const missing = [];
+    if (!appId)
+        missing.push("PUSHER_APP_ID");
+    if (!key)
+        missing.push("PUSHER_KEY");
+    if (!secret)
+        missing.push("PUSHER_SECRET");
+    if (!cluster)
+        missing.push("PUSHER_CLUSTER");
+    if (missing.length > 0) {
+        throw new Error(`Missing required environment variables: ${missing.join(", ")}. ` +
+            "Set these in your MCP server configuration or .env file.");
+    }
+    client = new Pusher({
+        appId: appId,
+        key: key,
+        secret: secret,
+        cluster: cluster,
+        useTLS: true,
+    });
+    return client;
+}

package/build/tools/authorize-channel.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { getPusherClient } from "../pusher-client.js";
+export function registerAuthorizeChannel(server) {
+    server.tool("authorize_channel", "Generate an authorization token for a private or presence channel. Useful when building auth endpoints for Pusher client connections.", {
+        socketId: z
+            .string()
+            .min(1)
+            .describe("The socket ID from the client connection"),
+        channel: z
+            .string()
+            .min(1)
+            .max(200)
+            .describe("Private or presence channel name (must start with 'private-' or 'presence-')"),
+        presenceData: z
+            .object({
+            user_id: z.string().min(1).describe("Unique user identifier"),
+            user_info: z
+                .record(z.unknown())
+                .optional()
+                .describe("Optional user metadata (name, avatar, etc.)"),
+        })
+            .optional()
+            .describe("Required for presence channels — identifies the connecting user"),
+    }, async ({ socketId, channel, presenceData }) => {
+        try {
+            if (!channel.startsWith("private-") &&
+                !channel.startsWith("presence-")) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: 'Channel must start with "private-" or "presence-" for authorization',
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            if (channel.startsWith("presence-") && !presenceData) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "presenceData is required for presence channels",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const pusher = getPusherClient();
+            const auth = pusher.authorizeChannel(socketId, channel, presenceData);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Authorization for ${channel}:\n${JSON.stringify(auth, null, 2)}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to authorize channel: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/get-channel-info.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { getPusherClient } from "../pusher-client.js";
+export function registerGetChannelInfo(server) {
+    server.tool("get_channel_info", "Get detailed information about a specific Pusher channel, including whether it is occupied and optional subscription/user counts.", {
+        channel: z
+            .string()
+            .min(1)
+            .max(200)
+            .describe("The channel name to query"),
+        info: z
+            .array(z.enum(["user_count", "subscription_count"]))
+            .optional()
+            .describe("Additional attributes to request"),
+    }, async ({ channel, info }) => {
+        try {
+            const pusher = getPusherClient();
+            const params = {};
+            if (info && info.length > 0)
+                params.info = info.join(",");
+            const response = await pusher.get({
+                path: `/channels/${encodeURIComponent(channel)}`,
+                params,
+            });
+            if (response.status !== 200) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Pusher API returned status ${response.status} for channel "${channel}"`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const body = (await response.json());
+            const lines = [`Channel: ${channel}`];
+            if (body.occupied !== undefined)
+                lines.push(`Occupied: ${body.occupied}`);
+            if (body.subscription_count !== undefined)
+                lines.push(`Subscriptions: ${body.subscription_count}`);
+            if (body.user_count !== undefined)
+                lines.push(`Users: ${body.user_count}`);
+            return {
+                content: [{ type: "text", text: lines.join("\n") }],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to get channel info: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/get-presence-users.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { getPusherClient } from "../pusher-client.js";
+export function registerGetPresenceUsers(server) {
+    server.tool("get_presence_users", "List all users currently connected to a presence channel. Only works with channels that start with 'presence-'.", {
+        channel: z
+            .string()
+            .min(1)
+            .max(200)
+            .startsWith("presence-", {
+            message: "Channel must be a presence channel (starts with 'presence-')",
+        })
+            .describe("Presence channel name (must start with 'presence-')"),
+    }, async ({ channel }) => {
+        try {
+            const pusher = getPusherClient();
+            const response = await pusher.get({
+                path: `/channels/${encodeURIComponent(channel)}/users`,
+                params: {},
+            });
+            if (response.status !== 200) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Pusher API returned status ${response.status} for channel "${channel}"`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const body = (await response.json());
+            const users = body.users || [];
+            if (users.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No users connected to ${channel}`,
+                        },
+                    ],
+                };
+            }
+            const userList = users.map((u) => `  ${u.id}`).join("\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Users on ${channel} (${users.length}):\n${userList}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to get presence users: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/list-channels.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { getPusherClient } from "../pusher-client.js";
+export function registerListChannels(server) {
+    server.tool("list_channels", "List all active channels in your Pusher app. Optionally filter by prefix (e.g. 'presence-' or 'private-') and request subscription or user counts.", {
+        prefix: z
+            .string()
+            .optional()
+            .describe("Filter channels by prefix (e.g. 'presence-', 'private-chat-')"),
+        info: z
+            .array(z.enum(["user_count", "subscription_count"]))
+            .optional()
+            .describe("Additional attributes to include for each channel"),
+    }, async ({ prefix, info }) => {
+        try {
+            const pusher = getPusherClient();
+            const params = {};
+            if (prefix)
+                params.filter_by_prefix = prefix;
+            if (info && info.length > 0)
+                params.info = info.join(",");
+            const response = await pusher.get({
+                path: "/channels",
+                params,
+            });
+            if (response.status !== 200) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Pusher API returned status ${response.status}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const body = (await response.json());
+            const channels = body.channels || {};
+            const names = Object.keys(channels);
+            if (names.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: prefix
+                                ? `No active channels matching prefix "${prefix}"`
+                                : "No active channels",
+                        },
+                    ],
+                };
+            }
+            const lines = names.map((name) => {
+                const ch = channels[name];
+                const parts = [name];
+                if (ch.subscription_count !== undefined)
+                    parts.push(`subscriptions: ${ch.subscription_count}`);
+                if (ch.user_count !== undefined)
+                    parts.push(`users: ${ch.user_count}`);
+                return parts.join(" — ");
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Active channels (${names.length}):\n${lines.join("\n")}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to list channels: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/terminate-user.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { getPusherClient } from "../pusher-client.js";
+export function registerTerminateUser(server) {
+    server.tool("terminate_user_connections", "Disconnect all connections for a specific user. Useful for moderation or security — forces a user offline across all channels.", {
+        userId: z
+            .string()
+            .min(1)
+            .describe("The user ID to disconnect from all channels"),
+    }, async ({ userId }) => {
+        try {
+            const pusher = getPusherClient();
+            await pusher.terminateUserConnections(userId);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `All connections terminated for user "${userId}"`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to terminate user connections: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/trigger-batch-events.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { getPusherClient } from "../pusher-client.js";
+export function registerTriggerBatchEvents(server) {
+    server.tool("trigger_batch_events", "Send up to 10 events in a single API call. More efficient than triggering events individually when you need to notify multiple channels.", {
+        events: z
+            .array(z.object({
+            channel: z
+                .string()
+                .min(1)
+                .max(200)
+                .describe("Target channel name"),
+            name: z.string().min(1).max(200).describe("Event name"),
+            data: z
+                .union([z.string(), z.record(z.unknown())])
+                .describe("Event payload"),
+            socketId: z.string().optional().describe("Socket ID to exclude"),
+        }))
+            .min(1)
+            .max(10)
+            .describe("Array of events to send (max 10)"),
+    }, async ({ events }) => {
+        try {
+            const pusher = getPusherClient();
+            const batch = events.map((e) => ({
+                channel: e.channel,
+                name: e.name,
+                data: typeof e.data === "string" ? e.data : JSON.stringify(e.data),
+                ...(e.socketId ? { socket_id: e.socketId } : {}),
+            }));
+            await pusher.triggerBatch(batch);
+            const summary = events
+                .map((e) => `  "${e.name}" → ${e.channel}`)
+                .join("\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Batch of ${events.length} event(s) triggered:\n${summary}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to trigger batch events: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/trigger-event.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { getPusherClient } from "../pusher-client.js";
+export function registerTriggerEvent(server) {
+    server.tool("trigger_event", "Send an event to one or more Pusher channels. Use this to push realtime messages to connected clients.", {
+        channel: z
+            .union([
+            z.string().min(1).max(200),
+            z.array(z.string().min(1).max(200)).min(1).max(100),
+        ])
+            .describe("Channel name or array of channel names (max 100)"),
+        event: z
+            .string()
+            .min(1)
+            .max(200)
+            .describe("Event name to trigger (e.g. 'new-message', 'update')"),
+        data: z
+            .union([z.string(), z.record(z.unknown())])
+            .describe("Event payload — string or JSON object (max 10KB)"),
+        socketId: z
+            .string()
+            .optional()
+            .describe("Optional socket ID to exclude from receiving the event (prevents echo)"),
+    }, async ({ channel, event, data, socketId }) => {
+        try {
+            const pusher = getPusherClient();
+            const payload = typeof data === "string" ? data : JSON.stringify(data);
+            const params = socketId ? { socket_id: socketId } : undefined;
+            await pusher.trigger(channel, event, payload, params);
+            const channels = Array.isArray(channel) ? channel : [channel];
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Event "${event}" triggered on ${channels.length} channel(s): ${channels.join(", ")}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to trigger event: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@crashbytes/pusher-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for Pusher Channels — trigger events, query channels, and manage realtime messaging from AI agents",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "pusher-mcp-server": "./build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "dev": "tsx src/index.ts",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "files": [
+    "build"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "pusher",
+    "realtime",
+    "websockets",
+    "ai",
+    "claude"
+  ],
+  "mcpName": "io.github.crashbytes/pusher-mcp-server",
+  "author": "CrashBytes",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CrashBytes/pusher-mcp-server.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "pusher": "^5.2.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  }
+}