# 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 **70 tools** covering all aspects of the Brainbase API:

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

### 💬 Chat Deployments (6 tools)
- Manage chat deployments
- Deploy and configure chat agents
- Query by deployment ID or agent ID

### 🎤 Voice Deployments (11 tools)
- Create and manage voice deployments
- Configure custom webhooks
- Make batch voice calls
- Get deployment analytics

### 🎤 Voice V1 Deployments (11 tools)
- Legacy voice deployment management
- Campaign management
- Batch calling capabilities

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

### 📁 Folders (6 tools)
- Organize resources with folders
- Hierarchical folder structure
- Move resources between folders

### 📄 Resources (4 tools)
- Manage file and link resources
- Vector search (RAG) capabilities
- Move and organize resources

### 📎 File Resources (2 tools)
- Upload and manage file resources
- Associate files with workers

### 🔗 Link Resources (2 tools)
- Create and manage link resources
- Web content integration

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

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

### 🧪 Tests (5 tools)
- Create and manage tests
- Run test suites
- View test run history

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

### 📊 Logs & Analysis (5 tools)
- Chat deployment logs
- Voice deployment logs
- Voice analytics with billing breakdown

## Installation

### Using pip

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

### Using uv (recommended)

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

### From source

```bash
git clone https://github.com/brainbase-mcp/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": "python",
      "args": ["-m", "server"],
      "env": {
        "BRAINBASE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Alternative: Using uv

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

## 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"
```

### Creating Chat Deployments

```
Create a chat deployment for worker "worker_123" named "Website Chat" using flow "flow_456"
```

```
List all chat deployments for worker "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
```

### Managing Resources

```
Create a file resource named "Product Manual" for worker "worker_123" with URL "https://example.com/manual.pdf"
```

```
Query resources for worker "worker_123" with query "pricing information"
```

### 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
```

### Organizing with Folders

```
Create a folder named "Documentation" for worker "worker_123"
```

```
Move resource "resource_123" to folder "folder_456"
```

## API Coverage

This MCP server implements all 70 endpoints from the Brainbase API v2:

| Category | Endpoints |
|----------|-----------|
| Workers | 5 |
| Chat Deployments | 6 |
| Voice Deployments | 11 |
| Voice V1 Deployments | 11 |
| Flows | 5 |
| Folders | 6 |
| Resources | 4 |
| File Resources | 2 |
| Link Resources | 2 |
| Integrations | 4 |
| Team | 1 |
| Tests | 5 |
| Assets | 3 |
| Logs | 4 |
| Analysis | 1 |
| **Total** | **70** |

## 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/brainbase-mcp/brainbase-mcp/issues

## 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-08)

- Initial release
- All 70 Brainbase API endpoints implemented
- Comprehensive test suite
- Full MCP protocol support
- API key authentication