BrainVlt — mcp-brain
Persistent AI memory you own and control.
Give Claude, Cursor, and every other AI client a persistent memory that travels with you — self-hosted, version-controlled, and never uploaded to any third-party cloud.
Website · Docs · Quick start
What is it?
mcp-brain is a personal Model Context Protocol server. Every MCP-compatible AI client — Claude Code, claude.ai, Cursor, Windsurf, custom GPTs, n8n — can read from and write to a shared knowledge store as long as it holds a valid token.
Your notes stay in plain-text markdown files on a machine you control. A git repository inside the container tracks every change with a full audit trail. Nothing leaves your host.
Features
| Feature | Description |
|---|
| 🧠 | Knowledge base | Markdown files with H2 sections; file-locked section-level updates; git auto-commit on every write |
| 📥 | Inbox | Staging area for scraped or draft info — always human-reviewed before it lands in the KB |
| ⚡ | Briefing | Session bootstrap: one call loads your personal context so the AI never starts cold |
| 🔑 | Secrets schema | Tells the AI which secrets exist and where; never stores the values themselves |
| 🔒 | Multi-token auth | Fine-grained per-scope bearer tokens — Claude Code gets *, Cursor gets knowledge:read:school |
| 🌐 | OAuth 2.1 server | DCR + PKCE + rotating refresh tokens so claude.ai Custom Connectors work without static headers |
| 📋 | Todoist integration | Read and create tasks; list projects and sections |
| 📅 | Google Calendar | Read events, create events, list calendars |
| 📝 | Nextcloud Notes | Browse and read your Nextcloud files |
| 🗂 | Trello | Read boards, lists, and cards; add cards |
| 📊 | Structured logging | JSON tool-call log per request: token id, tool name, duration, HTTP status |
| ♻️ | Hot-reload auth | Edit auth.yaml and tokens update within 5 s — no container restart |
Supported AI clients
| Client | Transport | How to connect |
|---|
| Claude Code (CLI) | Streamable HTTP | ~/.claude.json — bearer header |
| claude.ai (web / iOS / Android / desktop) | OAuth 2.1 | Customize → Connectors → Add custom connector |
| Cursor | Streamable HTTP | MCP settings — bearer header |
| Windsurf | Streamable HTTP | MCP settings — bearer header |
| ChatGPT / custom GPTs | Streamable HTTP | Plugin manifest — bearer header |
| n8n | Streamable HTTP | MCP node — bearer header |
| Any MCP client | Streamable HTTP | One URL + one header |
Quick start (any Docker host)
Runs on any Linux, macOS, or Windows machine with Docker Compose installed.
# 1. Grab the compose file and env template
curl -fsSL https://raw.githubusercontent.com/RyKaT07/mcp-brain/main/docker-compose.yml -o docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/RyKaT07/mcp-brain/main/.env.example -o .env
# 2. Generate the required admin secret
echo "MCP_OAUTH_ADMIN_SECRET=$(openssl rand -hex 32)" >> .env
# 3. Create a minimal auth file
mkdir -p data
cat > data/auth.yaml <<'EOF'
tokens:
- id: my-claude-code
token: "tok_changeme_replace_with_openssl_rand_hex_32"
scopes: ["*"]
EOF
# 4. Start
docker compose pull && docker compose up -d
# 5. Verify
curl http://127.0.0.1:8400/healthz
# → {"status":"ok"}
Port 8400 binds to 127.0.0.1 by default. Put Caddy, Traefik, or nginx with TLS in front before exposing it remotely. Full guide: docs/deployment.md.
Quick start (Proxmox VE)
One command on the Proxmox host shell provisions a fresh Debian LXC with Docker and mcp-brain already running:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/RyKaT07/mcp-brain/main/scripts/proxmox-install.sh)"
Or on any existing Debian/Ubuntu box:
bash <(curl -fsSL https://raw.githubusercontent.com/RyKaT07/mcp-brain/main/scripts/install.sh)
Full walkthrough: docs/deployment.md.
Connect from Claude Code
Add to ~/.claude.json: