egrigokhan/brainbase-mcp

Brainbase MCP Server

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

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

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

Using uv (recommended)

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

From source

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
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": "python",
      "args": ["-m", "server"],
      "env": {
        "BRAINBASE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Alternative: Using uv

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

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