npm package: @kafkahq/brainbase-mcp
Description: MCP server for Brainbase API - provides 25+ tools for managing workers, flows, voice deployments, and more
Author: Gokhan Egri
Latest version: 1.0.2

# Brainbase MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to the [Brainbase API](https://docs.usebrainbase.com/).

## Features

This MCP server exposes **25 active tools** for the Brainbase API (44 tools commented out for streamlined deployment):

### 🤖 Workers (5 tools)
- Create, read, update, and delete workers
- List all workers for your team

### 🎤 Voice Deployments (5 tools)
- Create and manage voice deployments
- Make batch voice calls
- Delete deployments

### 📊 Flows (5 tools)
- Create and manage conversation flows
- Update flow definitions
- List flows by worker

### 🔌 Integrations (4 tools)
- Twilio integration management
- Configure external services

### 👥 Team (1 tool)
- Get team information

### 📞 Assets (3 tools)
- Manage phone numbers
- Register Twilio numbers

### 📊 Logs (2 tools)
- Voice deployment logs
- Call logs with detailed analytics

## Installation

### Using npm (recommended)

```bash
npm install -g @egrigokhan/brainbase-mcp
```

After installation, run the install script:
```bash
cd $(npm root -g)/@egrigokhan/brainbase-mcp && ./install.sh
```

### Using pip

```bash
pip install git+https://github.com/egrigokhan/brainbase-mcp.git
```

### Using uv

```bash
uv pip install git+https://github.com/egrigokhan/brainbase-mcp.git
```

### From source

```bash
git clone https://github.com/egrigokhan/brainbase-mcp.git
cd brainbase-mcp
pip install -e .
```

## Configuration

### Get your Brainbase API Key

1. Go to [Brainbase](https://usebrainbase.com/)
2. Sign in to your account
3. Navigate to Settings → API Keys
4. Create a new API key or copy your existing key

### Configure Claude Desktop

Add this to your Claude Desktop configuration file:

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

```json
{
  "mcpServers": {
    "brainbase": {
      "command": "python3",
      "args": ["/path/to/brainbase-mcp/server.py"],
      "env": {
        "BRAINBASE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Replace `/path/to/brainbase-mcp/server.py` with the actual path. If you installed via npm, the path will be:
- **macOS/Linux**: `$(npm root -g)/@egrigokhan/brainbase-mcp/server.py`
- **Windows**: `%APPDATA%\npm\node_modules\@egrigokhan\brainbase-mcp\server.py`

## Usage

Once configured, the Brainbase tools will be available in Claude Desktop. You can:

### Managing Workers

```
Create a new worker named "Customer Support Bot" with description "Handles customer inquiries"
```

```
List all workers for my team
```

```
Get details for worker with ID "worker_123"
```

### Voice Deployments

```
Create a voice deployment for worker "worker_123" named "Sales Calls" using flow "flow_789"
```

```
Make batch calls with voice deployment "deploy_123" to these numbers: +1234567890, +1987654321
```

### Working with Flows

```
Create a new flow for worker "worker_123" named "Support Flow" with description "Customer support conversation flow"
```

```
Update flow "flow_123" with new definition
```

## API Coverage

This MCP server has 25 active tools (44 tools commented out):

| Category | Active Tools |
|----------|--------------|
| Workers | 5 |
| Voice Deployments | 5 |
| Flows | 5 |
| Integrations | 4 |
| Team | 1 |
| Assets | 3 |
| Logs | 2 |
| **Total Active** | **25** |

**Note**: 44 additional tools (chat deployments, voice webhooks, tests, resources, folders, chat logs, voice analysis, voice v1 deployments) are commented out in the source code and can be re-enabled if needed.

## Development

### Running Tests

```bash
# Install dev dependencies
pip install pytest pytest-asyncio

# Run tests
pytest test_server.py -v
```

### Project Structure

```
brainbase-mcp/
├── server.py           # Main MCP server implementation
├── test_server.py      # Comprehensive test suite
├── pyproject.toml      # Project configuration
└── README.md           # This file
```

## API Documentation

For detailed information about each endpoint, parameters, and response formats, see the official [Brainbase API Documentation](https://docs.usebrainbase.com/api-reference).

## Authentication

All requests are authenticated using your Brainbase API key via the `x-api-key` header. The API key must be set in the `BRAINBASE_API_KEY` environment variable.

## Error Handling

The server provides clear error messages for:
- Missing or invalid API key
- HTTP errors (4xx, 5xx)
- Network errors
- Invalid parameters

## Support

- **Brainbase Documentation**: https://docs.usebrainbase.com/
- **MCP Documentation**: https://modelcontextprotocol.io/
- **Issues**: https://github.com/egrigokhan/brainbase-mcp/issues
- **NPM Package**: https://www.npmjs.com/package/@egrigokhan/brainbase-mcp

## License

MIT License - see LICENSE file for details

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Changelog

### v1.0.0 (2025-10-09)

- Initial release
- 25 active Brainbase API tools (44 commented out for streamlined deployment)
- Fixed all implementations to match official Brainbase API specifications
- Comprehensive test suite
- Full MCP protocol support
- API key authentication
- NPM package distribution