pumble-mcp

A small MCP server that wraps Pumble's "API Key addon" REST API, exposing nineteen tools to any MCP client, covering messages and threads, scheduled messages, reactions, search, channel and membership management, direct messages, and the workspace user directory. See SPEC.md for the full design.

Security note: the Pumble API key you configure grants broad, workspace-wide access. Read the Security / Permissions section before installing.

1. Get a Pumble API key

1. In your Pumble workspace, install the API Key addon (Apps/Integrations).

2. Generate a key from the addon's settings. Pumble shows it once as an ephemeral message — copy it immediately.

Related MCP server: plutio-mcp

2. Configure the key

The server reads PUMBLE_API_KEY from its own environment. It does not load a .env file on its own, so set the variable one of these two ways.

For running the server directly (npm run dev, npm start), export it in your shell — add this to ~/.bashrc to make it stick:

export PUMBLE_API_KEY="<your key>"

For normal use through an MCP client, pass it in the client's env block instead — see step 4. That is the usual path, and it needs nothing in your shell.

.env.example lists the variables the server understands. If you keep a local .env for your own tooling, it is gitignored — never commit it.

3. Install, build

npm install
npm run build

4. Register with an MCP client

The server speaks MCP over stdio, so any MCP-capable client can run it. Point the client at the built entry point using an absolute path, and pass PUMBLE_API_KEY through the environment:

{
  "command": "node",
  "args": ["/absolute/path/to/pumble-mcp/dist/index.js"],
  "env": { "PUMBLE_API_KEY": "<your key>" }
}

Claude Code can write that entry for you. Run this from the project root so $(pwd) resolves correctly:

claude mcp add pumble --env PUMBLE_API_KEY="$PUMBLE_API_KEY" -- node "$(pwd)/dist/index.js"

Once registered, all nineteen tools are available in future sessions. Verify with:

claude mcp list

Development

npm run dev         # watch mode
npm run typecheck   # tsc --noEmit
npm test            # vitest

Tools

Messages & threads

channelIdentifier accepts either a channel name or a 24-character ID — names are resolved for you, and an ambiguous name is rejected rather than guessed.

Thread paging is inclusive: cursor names the reply to resume from and that reply comes back again, so cursor plus limit: N returns N + 1 items. The response carries no hasMore flag; a short page means the end.

Scheduled messages

Naming a destination by anything other than channelId costs an extra lookup: these endpoints only accept channelId, so channel names, user IDs, and emails are resolved first. Targeting a person resolves to the existing DM channel with them — Pumble creates one only after a first message, so DM someone before scheduling to them.

Editing is read-modify-write because Pumble rejects an edit missing any of channelId, text, or sendAt; fields you leave out are read back and resent unchanged. There is no separate "get" tool — listing already returns whole messages.

Reactions

Channels

Workspace

Security / Permissions

This server hands a single static Pumble API key to an MCP server that any connected client can call. Understand the blast radius before installing:

• The API key inherits the full visibility and privileges of the Pumble user who generated it. It is a password-equivalent secret.

• With these nineteen tools, anyone able to invoke this server (including any model or client session configured with it) can, as you:

  • read, send, edit, and reply to messages in any channel the key can see, including thread replies;

  • queue messages to post later in any channel or DM, and read, rewrite, redirect, or cancel anything already queued — a scheduled message can fire long after the session that created it has ended;

  • search across the workspace by text, author, or channel (pumble_search_messages) — this makes bulk retrieval far easier than reading channels one at a time;

  • send direct messages to any user (pumble_send_dm);

  • enumerate every workspace member's name and email (pumble_list_users);

  • read DM history — pumble_list_channels returns DM channels (channelType DIRECT), whose channelId feeds pumble_list_messages;

  • create channels and change who is in them — adding members exposes channel history to those users, and removing them revokes access (pumble_remove_user_from_channel demands confirm: true, which stops an accidental call but not a deliberate one);

  • react to messages as you (pumble_add_reaction).

• There is no per-tool scoping and no read-only mode: one key means full read/write across channels, DMs, and the user directory.

Recommendations:

• Never commit .env (it is gitignored). Do not paste the key into logs, issues, or chat.

• If the key is ever exposed, rotate it: generate a new key in the API Key addon, update .env, confirm it works, then revoke the old key.

• If your workspace allows it, generate the key from a dedicated, least-privilege service account rather than a full-admin user.