npm package: @phillmorgan28/pumble-mcp
Description: MCP server for Pumble workspace access - gives Claude deep context from team conversations
Author: Phill Morgan
Latest version: 2.0.0

# Pumble MCP Server

An MCP (Model Context Protocol) server that gives Claude deep access to Pumble workspace conversations. Claude can discover channels, retrieve full message histories, read threads, and gather context from team discussions.

## Features

- **Channel Discovery** — List, search, and filter channels by name pattern
- **Full Message History** — Cursor-based pagination with date filtering
- **Thread Support** — Retrieve thread replies with batch fetching
- **User Resolution** — Display names instead of user IDs
- **Token Optimized** — CSV output for lists, 24K token limit enforcement
- **Summary Mode** — Channel overviews without fetching all messages

## Setup

### 1. Get a Pumble API Key

1. Using a workspace admin account, enable the API Keys integration for your workspace
2. Open the API Keys integration chat channel
3. Generate a new API key
4. Copy the key

### 2. Configure Claude Desktop

Add to your `claude_desktop_config.json`:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "pumble": {
      "command": "npx",
      "args": ["-y", "@phillmorgan28/pumble-mcp"],
      "env": {
        "PUMBLE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### 3. Configure Claude Code CLI

```bash
claude mcp add pumble -s user -e PUMBLE_API_KEY=your-api-key-here -- npx -y @phillmorgan28/pumble-mcp
```

## Available Tools

| Tool | Description |
|------|-------------|
| `list_channels` | Get all channels in the workspace (CSV format) |
| `get_channel` | Get a specific channel by name or ID |
| `search_channels` | Find channels matching a pattern |
| `list_messages` | Retrieve messages with pagination and date filtering |
| `list_users` | Get all workspace users (CSV format) |
| `get_thread_replies` | Get all replies in a thread |
| `get_multiple_threads` | Batch fetch multiple threads |

## Usage Examples

Once configured, Claude can:

**Find project channels:**
> "What Pumble channels exist for the website project?"

**Get recent discussions:**
> "Show me what the team discussed in #project-foo this week"

**Gather context before work:**
> "Before I start on this feature, check Pumble for any relevant discussions"

**Follow thread conversations:**
> "Get the full thread discussion about the API changes"

**Channel overview:**
> "Give me a summary of activity in #general"

## Tool Parameters

### list_messages

| Parameter | Type | Description |
|-----------|------|-------------|
| `channelName` | string | Channel name (e.g., "general") |
| `channelId` | string | Channel ID (alternative to name) |
| `limit` | number | Messages to retrieve (1-100, default 20) |
| `cursor` | string | Pagination cursor from previous response |
| `afterDays` | number | Only messages from last N days |
| `after` | string | ISO date — messages after this date |
| `before` | string | ISO date — messages before this date |
| `summary` | boolean | Return channel summary instead of messages |

### get_thread_replies

| Parameter | Type | Description |
|-----------|------|-------------|
| `channelId` | string | Channel containing the thread |
| `messageId` | string | ID of the thread root message |
| `limit` | number | Max replies to return (1-100, default 25) |

### get_multiple_threads

| Parameter | Type | Description |
|-----------|------|-------------|
| `threads` | array | Array of `{channelId, messageId}` (max 5) |
| `limit` | number | Max replies per thread (1-50, default 10) |

## Requirements

- Node.js 22+
- Pumble API key
- Claude Desktop or Claude Code CLI

## Troubleshooting

### npx "command not found" error

If you get `sh: pumble-mcp: command not found` when using npx, clear the npx cache:

```bash
rm -rf ~/.npm/_npx
```

Then try again. This happens when the npx cache becomes stale or corrupted.

## License

MIT