pumble-mcp

A small MCP server that wraps Pumble's "API Key addon" REST API, exposing six tools to Claude Code: send a message, list channel messages, edit a message, list channels, send a direct message, and list workspace users. 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

cp .env.example .env
# edit .env and set PUMBLE_API_KEY=<your key>

.env is gitignored — never commit it. If you'd rather set it globally for your shell (so any tool can use it without a .env file), add to ~/.bashrc:

export PUMBLE_API_KEY="<your key>"

3. Install, build

npm install
npm run build

4. Register with Claude Code

Register this as an MCP server using the absolute path to the built entry point on your machine. 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"

This writes an entry for pumble into Claude Code's MCP server config so future sessions automatically have all six tools available, the same way Slack's tools show up as mcp__plugin_slack_slack__*.

Verify it's registered:

claude mcp list

Development

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

Tools

Security / Permissions

This server hands a single static Pumble API key to an MCP server that Claude Code 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 six tools, anyone able to invoke this server (including any Claude session configured with it) can, as you:

  • read, send, and edit messages in any channel the key can see;

  • 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.

• 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.