Filesystem + repo tools (7, NEW in v0.2)

Path safety is baked in: .. escapes are rejected, and a deny-list filters .env*, *credentials*, *secret*, id_rsa*, *.pem, *.key, *.pfx, plus huge dirs like node_modules, .git, .next, __pycache__. 22 dedicated tests cover these rules.

Resources (4)

• bbrain://identity — who I am + role context (so Claude doesn't call me a "founder" when I'm a Technical Lead)
• bbrain://infrastructure — vault's self-description
• bbrain://session-briefing — pre-baked briefing file
• bbrain://roots — live list of configured filesystem roots

Prompts (1)

• start_session — pickable from Claude Desktop's prompt picker

Install

git clone https://github.com/vijayarajanandan/bigboost-brain-mcp
cd bigboost-brain-mcp
pip install -e .

Configure roots

By default the MCP exposes four roots: the vault itself plus cosma-frontend, bigboost-os-backend, and bigboost-brain-mcp. Override with the BBRAIN_ROOTS env var:

export BBRAIN_ROOTS="vault=/Users/me/Vault;api=/Users/me/code/api;web=/Users/me/code/web"

BBRAIN_VAULT_ROOT separately controls the vault path used by the structured vault tools (list_stories, etc.) — set it if your vault isn't at the default BigBoost location.

Mode 1 — Claude Desktop / Claude Code (stdio, local)

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (Mac):

{
  "mcpServers": {
    "bigboost-brain": {
      "command": "python",
      "args": ["-m", "bigboost_brain_mcp"],
      "env": {
        "BBRAIN_VAULT_ROOT": "C:/path/to/your/vault",
        "BBRAIN_ROOTS": "vault=C:/path/to/your/vault;api=C:/path/to/api"
      }
    }
  }
}

Restart Claude Desktop. Tools appear in the picker. Test with:

Use session_start from bigboost-brain to brief me.

For Claude Code (CLI), register the same way via claude mcp add.

Mode 2 — claude.ai web (HTTP + Cloudflare Tunnel)

claude.ai web supports custom remote MCP connectors (Free / Pro / Max / Team / Enterprise plans). Anthropic's cloud connects to your MCP from their IPs, so the server has to be reachable on the public internet. The recommended path keeps the vault on your laptop and uses a Cloudflare Tunnel for the public reachability + TLS.

Step 1 — generate a bearer token

python -c "import secrets; print(secrets.token_urlsafe(32))"
# → e.g. 4nT6wZv9...UhqCk_LmXp
export BBRAIN_AUTH_TOKEN='4nT6wZv9...UhqCk_LmXp'

Step 2 — start the HTTP server

bigboost-brain-mcp-http --host 127.0.0.1 --port 8765

The server refuses to start without a token (and refuses short ones). On boot you'll see:

[bbrain] starting HTTP MCP on http://127.0.0.1:8765
         auth: bearer token (len=43)
         mcp endpoint: /mcp  (POST, with Authorization header)
         health:       /health  (GET, no auth)

Step 3 — Cloudflare Tunnel (free, TLS automatic)

You need a domain on Cloudflare. Then:

# Install (macOS) — see https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads
brew install cloudflare/cloudflare/cloudflared
# Or Windows: download cloudflared.exe from the same page

cloudflared tunnel login                     # opens browser, picks your zone
cloudflared tunnel create bbrain             # creates the tunnel + cert
cloudflared tunnel route dns bbrain bbrain.your-domain.com

Create ~/.cloudflared/config.yml:

tunnel: bbrain
credentials-file: ~/.cloudflared/<tunnel-uuid>.json

ingress:
  - hostname: bbrain.your-domain.com
    service: http://127.0.0.1:8765
  - service: http_status:404

Run it:

cloudflared tunnel run bbrain
# Or install as a service: cloudflared service install

Step 4 — add the connector in claude.ai

In claude.ai → Customize → Connectors → + Add Custom Connector:

• Name: BigBoost Brain
• URL: https://bbrain.your-domain.com/mcp

Auth: claude.ai's connector dialog supports OAuth, but our minimal server uses bearer-token via the Authorization header. Two clean options:

(a) Cloudflare Access — recommended. Wrap the tunnel in Cloudflare's zero-trust layer (free for up to 50 users). Configure an Access policy that allows only your email. Cloudflare validates the user before forwarding to the MCP, and you can leave the bearer token in the URL as a defence-in-depth measure. claude.ai will prompt you to sign in via Google/GitHub on first use.

(b) Token in URL (simpler, less safe). Pass ?auth=... and modify the middleware to read it — see docs/auth-modes.md. Acceptable for personal use behind Cloudflare; not recommended for shared deployments.

For Claude Desktop / Claude Code clients connecting to the same HTTP MCP, just configure the bearer token in their connector config — both support custom auth headers natively.

Adapting to your own vault

Three paths from "useful for Vijay" → "useful for you":

1. Same structure, different files — set BBRAIN_VAULT_ROOT + BBRAIN_ROOTS and the tools work as-is if you adopt the directory conventions (Ralph/stories, Decisions, Capability, etc.).
2. Different structure — fork vault.py, change the VaultPaths dataclass to match your folder layout. Tools in server.py largely stay.
3. Total rebuild — this repo demonstrates the pattern (FastMCP + frontmatter parsing + structured queries over a vault + multi-root filesystem access + HTTP transport with auth). Roll your own with whatever schema fits your work.

Testing

pip install -e ".[test]"
pytest tests/ -v
# 44 passing — vault parsing (17), root + path safety (20), HTTP auth (7)

Why this exists

Most "second brain" setups optimize for note-taking. This one optimizes for agent safety + decision velocity — the brain isn't just notes, it's the operational nervous system for a small engineering org running a real production SaaS with 7 active clients. The MCP makes that brain queryable from anywhere Claude can run, without ever leaving the laptop where it lives.

If that resonates with your work, fork it.

License

MIT — see LICENSE.

Author

Vijayaraj Anandan — Technical Lead at BigBoost (Chennai). Builder of Cosma, Ralph, and other AI-shaped tools.

MCP server giving Claude AI access to 20+ NYC public-record datasets across 9 city agencies via 18 tools — NYC property due diligence in plain English: violations, liens, sales, ownership, permits, rent stabilization, and more.