Brainbase MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to the Brainbase API.

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)

npm install -g @egrigokhan/brainbase-mcp

After installation, run the install script:

cd $(npm root -g)/@egrigokhan/brainbase-mcp && ./install.sh

Using pip

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

Using uv

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

From source

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

{
  "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):

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

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

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