Installation

Get brain-mcp running in 5 minutes. Everything runs locally — no API keys required for core functionality.

Prerequisites

  • Python 3.11+ — for the MCP server and data pipelines
  • An MCP client — Claude Desktop, Cursor, Windsurf, or any MCP-compatible tool
  • ~2 GB disk space — for data, vectors, and the embedding model
  • macOS, Linux, or Windows — Apple Silicon recommended for fastest embeddings (works on Intel, CUDA, and CPU too)

Optional: mcporter

mcporter is a CLI tool for calling MCP servers from the command line. Useful for testing but not required — brain-mcp works directly with any MCP client.

Install

1

Install from PyPI

pip install brain-mcp

On Apple Silicon, this automatically installs PyTorch with MPS support for fast local embeddings.

Or install from source:

git clone https://github.com/mordechaipotash/brain-mcp.git
cd brain-mcp
pip install -e .
2

Set up brain-mcp

brain-mcp setup

This discovers available data sources, imports conversations, creates embeddings, and configures your MCP clients — all in one step. You'll be prompted to select which conversation sources to import.

3

Run the health check

brain-mcp doctor

Verifies all dependencies, checks data paths, and confirms the embedding model can load. Fix any issues it reports before continuing.

4

Configure your MCP client

The fastest way:

brain-mcp setup claude   # Auto-configure Claude Desktop

Or configure manually — see the client configuration section below.

Import Your Data

brain-mcp needs conversation data to work with. Import from any of these sources:

ChatGPT

Export your data from Settings → Data Controls → Export Data in ChatGPT. Place the conversations.json in the brain-mcp data directory.

Claude Desktop

brain-mcp reads Claude Desktop conversation logs from their default location. No export needed.

Claude Code / Clawdbot

Session transcripts are synced automatically via the sync pipeline.

brain-mcp setup handles syncing and embedding automatically. To manually sync later:

brain-mcp sync           # Manual sync of all conversation sources

Client Configuration

Claude Desktop

Config path varies by platform — brain-mcp setup claude handles this automatically. Manual config:

claude_desktop_config.json
{
  "mcpServers": {
    "my-brain": {
      "command": "brain-mcp",
      "args": ["serve"]
    }
  }
}

Cursor

Run brain-mcp setup cursor or add manually to .cursor/mcp.json:

.cursor/mcp.json
{
  "mcpServers": {
    "my-brain": {
      "command": "brain-mcp",
      "args": ["serve"]
    }
  }
}

Windsurf

Run brain-mcp setup windsurf or add manually to your Windsurf MCP configuration:

mcp_config.json
{
  "mcpServers": {
    "my-brain": {
      "command": "brain-mcp",
      "args": ["serve"]
    }
  }
}

Automatic setup

brain-mcp setup configures all detected MCP clients automatically. You only need manual configuration for custom setups.

Verify Installation

Open your MCP client and type “use brain”. You should see the AI call brain-mcp tools and return context from your conversation history.

You can also verify from the command line with mcporter:

# Install mcporter (optional CLI tool)
npm install -g mcporter

# Test a tool call
mcporter call brain.brain_stats

# Should return something like:
# 📊 Brain Stats
# Messages: 377,326 | Conversations: 12,847
# Embeddings: 82,000 | Summaries: 9,979

Next up

Now that you're set up, learn about the architecture or jump straight to the tools overview.

PreviousQuickstartNextArchitecture