Pumble MCP Server

A Model Context Protocol (MCP) server for Pumble, built with TypeScript using Test-Driven Development (TDD).

📦 Published on npm: @shoutkol/pumble-mcp-server

Overview

This MCP server provides integration with Pumble's API, allowing you to send messages, manage channels, react to messages, and interact with your Pumble workspace through MCP-compatible clients.

Prerequisites

Node.js (v18 or higher)
A Pumble API key (see API Key Setup)

Installation

Using npm (Recommended)

The package is published on npm: @shoutkol/pumble-mcp-server

No installation needed! Use it directly with npx:

npx -y @shoutkol/pumble-mcp-server

Or install globally:

npm install -g @shoutkol/pumble-mcp-server

Local Development

For local development and contributing:

# Clone the repository
git clone https://github.com/shoutkol/pumble-mcp-server.git
cd pumble-mcp-server

# Install dependencies
pnpm install

# Build the project
pnpm build

API Key Setup

To use this MCP server, you need a Pumble API key. Generate one by:

Installing the API app in your Pumble workspace
Typing /api-keys generate in any Pumble channel
Copying the generated API key from the ephemeral message

Configuration

The API key can be provided in two ways:

MCP Server Configuration (Recommended): Provide the API key in your MCP client configuration:

{
  "mcpServers": {
    "pumble": {
      "command": "npx",
      "args": ["-y", "@shoutkol/pumble-mcp-server"],
      "initializationOptions": {
        "apiKey": "your-api-key-here"
      }
    }
  }
}

Environment Variable: Set the PUMBLE_API_KEY environment variable:
```
export PUMBLE_API_KEY="your-api-key-here"
```
Then use it with:
```
npx -y @shoutkol/pumble-mcp-server
```

Development

# Run in development mode with hot reload
pnpm dev

# Build the project
pnpm build

# Run the built server
pnpm start

# Watch mode for building
pnpm watch

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

Testing with MCP Inspector

You can test the MCP server interactively using the MCP Inspector. To run it with your API key:

Option 1: Inline (single command)

PUMBLE_API_KEY="your-api-key-here" npx @modelcontextprotocol/inspector -- tsx src/index.ts

Option 2: Export first, then run

export PUMBLE_API_KEY="your-api-key-here"
npx @modelcontextprotocol/inspector -- tsx src/index.ts

Option 3: Using dotenv-cli

Create a .env file in your project root:

PUMBLE_API_KEY=your-api-key-here

Then run:

# Install dotenv-cli if needed: pnpm add -D dotenv-cli
npx dotenv-cli npx @modelcontextprotocol/inspector -- tsx src/index.ts

The inspector will open a web interface at http://localhost:6274 where you can:

View all available tools
Test tool calls interactively
See request/response details
Debug API interactions

Note: Replace "your-api-key-here" with your actual Pumble API key (generated with /api-keys generate in Pumble).

Testing

This project uses Test-Driven Development (TDD) with Vitest. Tests are located in src/__tests__/.

Running Tests

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

TDD Workflow

The project follows the Red-Green-Refactor cycle:

Red: Write tests first that define the desired functionality
Green: Implement minimal code to make tests pass
Refactor: Improve code while keeping tests green

Available Tools

`pumble_validate_api_key`

Validates the Pumble API key by making a test API call.

Parameters: None

Example:

{
  "tool": "pumble_validate_api_key",
  "arguments": {}
}

`pumble_send_message`

Send a message to a Pumble channel.

Parameters:

text (string, required): The message text to send
channel (string, optional): The channel name (use either channel or channelId)
channelId (string, optional): The channel ID (use either channel or channelId)
asBot (boolean, optional): Whether to send the message as a bot (default: true)

Example:

{
  "tool": "pumble_send_message",
  "arguments": {
    "text": "Hello from MCP!",
    "channel": "general",
    "asBot": true
  }
}

`pumble_send_reply`

Reply to a specific message in a Pumble channel.

Parameters:

text (string, required): The reply text
messageId (string, required): The ID of the message to reply to
channel (string, optional): The channel name (use either channel or channelId)
channelId (string, optional): The channel ID (use either channel or channelId)
asBot (boolean, optional): Whether to send the reply as a bot (default: true)

Example:

{
  "tool": "pumble_send_reply",
  "arguments": {
    "text": "This is a reply",
    "messageId": "65c4ba025f3c124940579c7f",
    "channel": "general",
    "asBot": true
  }
}

`pumble_add_reaction`

Add an emoji reaction to a message.

Parameters:

messageId (string, required): The ID of the message to react to
reaction (string, required): The emoji reaction code (e.g., :grin:)

Example:

{
  "tool": "pumble_add_reaction",
  "arguments": {
    "messageId": "65c4a8ab99f15a6b2150e0f0",
    "reaction": ":grin:"
  }
}

`pumble_create_channel`

Create a new channel in Pumble.

Parameters:

name (string, required): The name of the channel
type (string, required): The channel type (PUBLIC or PRIVATE)
description (string, optional): Optional channel description

Example:

{
  "tool": "pumble_create_channel",
  "arguments": {
    "name": "my-new-channel",
    "type": "PUBLIC",
    "description": "A new channel created via MCP"
  }
}

`pumble_delete_message`

Delete a message from a Pumble channel.

Parameters:

messageId (string, required): The ID of the message to delete
channel (string, optional): The channel name (use either channel or channelId)
channelId (string, optional): The channel ID (use either channel or channelId)

Example:

{
  "tool": "pumble_delete_message",
  "arguments": {
    "messageId": "65c4ba025f3c124940579c7f",
    "channel": "general"
  }
}

`pumble_list_messages`

List messages in a Pumble channel.

Parameters:

channel (string, optional): The channel name (use either channel or channelId)
channelId (string, optional): The channel ID (use either channel or channelId)
cursor (string, optional): Optional cursor for pagination
limit (number, optional): Optional limit for number of messages

Example:

{
  "tool": "pumble_list_messages",
  "arguments": {
    "channel": "general",
    "limit": 50
  }
}

`pumble_list_channels`

List all channels and DMs in the workspace.

Parameters: None

Example:

{
  "tool": "pumble_list_channels",
  "arguments": {}
}

`pumble_list_users`

List all users in the workspace.

Parameters: None

Example:

{
  "tool": "pumble_list_users",
  "arguments": {}
}

Usage

This MCP server can be used with MCP-compatible clients. Configure it in your MCP client settings to use stdio transport.

Installation via npm (npx)

Once published to npm, users can run this MCP server directly without installing it:

npx -y @shoutkol/pumble-mcp-server

Or with an API key:

PUMBLE_API_KEY="your-api-key-here" npx -y @shoutkol/pumble-mcp-server

Claude Desktop

Find your Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Add the Pumble MCP server configuration:

Using npx (Recommended):

{
  "mcpServers": {
    "pumble": {
      "command": "npx",
      "args": ["-y", "@shoutkol/pumble-mcp-server"],
      "initializationOptions": {
        "apiKey": "your-pumble-api-key"
      }
    }
  }
}

Using local installation:

{
  "mcpServers": {
    "pumble": {
      "command": "node",
      "args": ["/absolute/path/to/pumble-mcp-server/dist/index.js"],
      "initializationOptions": {
        "apiKey": "your-pumble-api-key"
      }
    }
  }
}

Using environment variable:

{
  "mcpServers": {
    "pumble": {
      "command": "npx",
      "args": ["-y", "@shoutkol/pumble-mcp-server"],
      "env": {
        "PUMBLE_API_KEY": "your-pumble-api-key"
      }
    }
  }
}

Restart Claude Desktop to load the new configuration.
Verify connection: Open Claude Desktop and check that the Pumble tools are available in the MCP tools list.

Cline (VS Code Extension)

Install Cline from the VS Code marketplace.
Open VS Code settings (Cmd/Ctrl + ,) and search for "Cline".
Add MCP server configuration in your VS Code settings.json:

{
  "cline.mcpServers": {
    "pumble": {
      "command": "npx",
      "args": ["-y", "@shoutkol/pumble-mcp-server"],
      "env": {
        "PUMBLE_API_KEY": "your-pumble-api-key"
      }
    }
  }
}

Reload VS Code to activate the configuration.

Other MCP Clients

For other MCP-compatible clients, configure the server using stdio transport:

Command: npx (or node for local installation)
Args: ["-y", "@shoutkol/pumble-mcp-server"] (or ["/path/to/dist/index.js"] for local)
API Key: Provide via initializationOptions.apiKey or PUMBLE_API_KEY environment variable

Using the Tools

Once configured, you can use the Pumble tools through your MCP client:

Send messages to channels
Reply to messages in threads
Add reactions to messages
Create channels (public or private)
List channels, users, and messages
Delete messages

The tools will appear in your MCP client's tool list and can be invoked through natural language or direct tool calls.

Deployment

Local Deployment

Prerequisites:

Node.js v18 or higher
pnpm installed globally

Steps:

Clone or download the repository:

git clone <repository-url>
cd pumble-mcp-server

Install dependencies:

pnpm install

Build the project:

pnpm build

Set up API key:

export PUMBLE_API_KEY="your-api-key-here"

Run the server:

pnpm start

The server runs on stdio transport and communicates with MCP clients via standard input/output.

Publishing to npm

To enable npx usage, publish the package to npm:

Manual Publishing:

Build the project:
```
pnpm build
```
Login to npm:
```
npm login
```
Publish:
```
npm publish
```
Verify it works:
```
npx -y @shoutkol/pumble-mcp-server
```

Automated Publishing with GitHub Actions:

The repository includes a GitHub Actions workflow for automated publishing to npm:

Set up npm token:
- Go to https://www.npmjs.com/settings/shoutkol/packages
- Create an "Automation" access token
- Add it as a secret named NPM_TOKEN in your GitHub repository settings:
  - Go to: Settings → Secrets and variables → Actions
  - Click "New repository secret"
  - Name: NPM_TOKEN
  - Value: Your npm automation token
  - Click "Add secret"
Create a release:
- Go to: https://github.com/shoutkol/pumble-mcp-server/releases/new
- Create a new release with a version tag (e.g., v0.1.0)
- The workflow will automatically:
  - Run tests
  - Build the project
  - Publish to npm registry at https://www.npmjs.com/settings/shoutkol/packages
Manual trigger:
- Go to Actions → Publish to npm → Run workflow
- Enter the version number and run

The workflow ensures that only tested and built code is published to npm.

Production Considerations

Security:
- Never commit API keys to version control
- Use environment variables or secret management services
- Consider using different API keys for development and production
Monitoring:
- Add logging for API calls and errors
- Monitor API rate limits
- Set up alerts for failures
Performance:
- The server is lightweight and runs on stdio
- No HTTP server overhead
- Consider connection pooling if handling multiple clients
Scaling:
- MCP servers typically run one instance per client connection
- For multiple clients, run multiple instances
- Consider using process managers like PM2 for local deployments

Environment Variables

Variable	Description	Required
`PUMBLE_API_KEY`	Your Pumble API key	Yes

Troubleshooting

Server won't start:

Verify Node.js version (v18+)
Check that dist/index.js exists (run pnpm build)
Verify API key is set correctly

Tools not appearing:

Check MCP client logs for connection errors
Verify the server path in configuration is absolute (if using local installation)
Ensure the server process has execute permissions

API errors:

Validate your API key with pumble_validate_api_key tool
Check API rate limits
Verify network connectivity to Pumble API

Connection issues:

Ensure stdio transport is configured correctly
Check that the server process is running
Review MCP client logs for detailed error messages

CI/CD

This project uses GitHub Actions for continuous integration and deployment:

Workflows

CI (ci.yml): Runs on every push and pull request
- Runs tests
- Builds the project
- Type checks the code
Publish to npm (publish-npm.yml): Runs on releases
- Runs tests
- Builds the project
- Publishes to npm registry at https://www.npmjs.com/settings/shoutkol/packages

Setting up Automated Publishing

Create npm access token:
- Go to https://www.npmjs.com/settings/shoutkol/packages
- Create a new "Automation" access token
- Copy the token
Add secret to GitHub:
- Go to your repository → Settings → Secrets and variables → Actions
- Click "New repository secret"
- Name: NPM_TOKEN
- Value: Your npm token
- Click "Add secret"
Create a release:
- Go to Releases → Create a new release
- Tag: v1.0.0 (or your version)
- Title: Release v1.0.0
- Description: Release notes
- Click "Publish release"
- The workflow will automatically publish to npm

Project Structure

.
├── .github/
│   └── workflows/
│       ├── ci.yml              # CI workflow
│       └── publish-npm.yml    # npm publishing workflow
├── src/
│   ├── index.ts               # Main server entry point
│   ├── pumble-client.ts       # Pumble API client
│   └── __tests__/
│       └── index.test.ts      # Test suite
├── dist/                      # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── vitest.config.ts          # Vitest configuration
└── README.md

Error Handling

The server provides comprehensive error handling:

Missing API Key: Clear error message if API key is not configured
API Errors: Detailed error messages with status codes from Pumble API
Network Errors: Handles network failures gracefully
Invalid Parameters: Validates required parameters and provides helpful error messages

API Reference

This server integrates with the Pumble API Addon. For more information about the Pumble API, see the official documentation.

Base URL: https://pumble-api-keys.addons.marketplace.cake.com

Authentication: All requests use the Api-Key header with your generated API key.

Docker Deployment

This MCP server can be deployed as a Docker container with HTTP/Streamable HTTP transport support, similar to gitlab-mcp.

Building the Docker Image

docker build -t pumble-mcp-server .

Running with Docker

docker run -i --rm \
  -p 3000:3000 \
  -e PUMBLE_API_KEY=your-api-key \
  pumble-mcp-server

The server will be available at:

Streamable HTTP endpoint: http://localhost:3000/mcp
Health check: http://localhost:3000/health

Using HTTP Transport

The HTTP server uses Streamable HTTP transport, which allows MCP clients to connect over HTTP instead of stdio.

Claude Desktop Configuration

{
  "mcpServers": {
    "pumble": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

Cline (VS Code) Configuration

{
  "cline.mcpServers": {
    "pumble": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Note: For HTTP transport, set the PUMBLE_API_KEY environment variable in the Docker container or pass it via the Authorization header.

Deploying to Docker Hub

Login to Docker Hub:
```
docker login
```

Set your Docker Hub username:

export DOCKER_USERNAME=your-dockerhub-username

Build and push using the script:

./deploy-dockerhub.sh

Or manually:

# Build the image
docker build -t your-username/pumble-mcp-server:latest .

# Push to Docker Hub
docker push your-username/pumble-mcp-server:latest

Run from Docker Hub:

docker run -p 3000:3000 \
  -e PUMBLE_API_KEY=your-api-key \
  your-username/pumble-mcp-server:latest

Deploying to Google Cloud Run

Set environment variables:

export GCP_PROJECT_ID=your-project-id
export PUMBLE_API_KEY=your-api-key

Deploy using the script:

./deploy-gcp.sh

Or manually:

# Build and push
docker build -t gcr.io/YOUR_PROJECT_ID/pumble-api-server .
docker push gcr.io/YOUR_PROJECT_ID/pumble-api-server

# Deploy to Cloud Run
gcloud run deploy pumble-api-server \
  --image gcr.io/YOUR_PROJECT_ID/pumble-api-server \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars PUMBLE_API_KEY=your-api-key \
  --port 3000

Running Modes

The server supports two modes:

Stdio Mode (default): For local MCP clients
```
pnpm start
# or
node dist/index.js
```
HTTP Mode: For remote access and Docker deployment
```
pnpm start:http
# or
node dist/http-server.js
```

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.github/workflows		.github/workflows
src		src
.cursorrules		.cursorrules
.dockerignore		.dockerignore
.gitignore		.gitignore
.npmignore		.npmignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
RELEASE_NOTES_v1.0.0.md		RELEASE_NOTES_v1.0.0.md
deploy-dockerhub.sh		deploy-dockerhub.sh
deploy-gcp.sh		deploy-gcp.sh
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Pumble MCP Server

Overview

Prerequisites

Installation

Using npm (Recommended)

Local Development

API Key Setup

Configuration

Development

Testing with MCP Inspector

Testing

Running Tests

TDD Workflow

Available Tools

pumble_validate_api_key

pumble_send_message

pumble_send_reply

pumble_add_reaction

pumble_create_channel

pumble_delete_message

pumble_list_messages

pumble_list_channels

pumble_list_users

Usage

Installation via npm (npx)

Claude Desktop

Cline (VS Code Extension)

Other MCP Clients

Using the Tools

Deployment

Local Deployment

Publishing to npm

Production Considerations

Environment Variables

Troubleshooting

CI/CD

Workflows

Setting up Automated Publishing

Project Structure

Error Handling

API Reference

Docker Deployment

Building the Docker Image

Running with Docker

Using HTTP Transport

Claude Desktop Configuration

Cline (VS Code) Configuration

Deploying to Docker Hub

Deploying to Google Cloud Run

Running Modes

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`pumble_validate_api_key`

`pumble_send_message`

`pumble_send_reply`

`pumble_add_reaction`

`pumble_create_channel`

`pumble_delete_message`

`pumble_list_messages`

`pumble_list_channels`

`pumble_list_users`

Packages