Big Brain

What Big Brain MCP server does

Big Brain MCP server gives an AI assistant structured access to a folder of Markdown files used as a personal knowledge base. The vault can contain notes, projects, tasks, inbox captures, daily journals, tags, frontmatter, and wiki-style links. It can use a new directory or read an existing Obsidian vault without migration.

The server exposes tools for inspecting current work, finding notes, reading and creating content, updating metadata, recording quick captures, and maintaining tasks and projects. It can also report outgoing links and backlinks, identify related notes, list tags, and surface vault issues such as broken links, malformed frontmatter, stale projects, duplicate or oversized notes, and overdue tasks.

How it works

The server reads and writes Markdown directly rather than using a separate database. Deterministic retrieval includes fuzzy full-text matching, title weighting, tags, frontmatter filters, and wiki-link relationships. Optional local embeddings add semantic matches and support related-note results; this requires the separate Transformers package and keeps processing on the device.

Local MCP clients connect through the stdio command big-brain-mcp. The vault is selected with a command-line option or the BIG_BRAIN_VAULT environment variable. A separate command can expose the same tools through Streamable HTTP on localhost, using a bearer token and optional origin restrictions. The HTTP preview should be placed behind an HTTPS reverse proxy or secure tunnel rather than exposed directly.

Writes are designed to avoid damaging existing files: note changes are atomic and locked per note, preserve line endings, avoid code blocks and frontmatter, and reject paths that resolve outside the vault. Optional Git settings can commit changed files and push them in the background; Git failures do not prevent a note save.

Setup and configuration

Node.js 20 or newer is required. Install the package globally with npm, then initialize a vault or point the server at an existing Markdown directory. The setup command can create a default vault, connect Claude Code and Codex when available, install related skills, and print configuration for other clients. It is safe to rerun, and a dry-run option shows intended changes first.

For manual setup, install the package, initialize the vault, and register big-brain-mcp in the client’s MCP configuration with an absolute executable path. Add --vault with the vault location, or configure BIG_BRAIN_VAULT. Folder mappings can be placed in brain.config.json; this lets project and inbox operations use folder names that differ from the defaults.

Semantic search is not included in the base installation. Enable it in configuration and install @huggingface/transformers in the same global installation location. Git auto-commit and auto-push are also opt-in configuration features.

Tools and capabilities

The available tool set covers:

• brain_overview for active projects, due or overdue tasks, inbox items, and recent notes.
• search_notes and read_note for filtered discovery and reading by path, title, alias, folder, type, or tag.
• create_note, update_frontmatter, and capture for writing notes, changing metadata, and adding inbox items.
• daily_note for daily entries and timestamped work journals.
• list_projects, list_tasks, and update_task for project and checkbox-task workflows.
• note_links and related_notes for graph and similarity-based navigation.
• list_tags for tag counts and vault-health findings.

Limitations and notes

Big Brain is pre-1.0, so minor releases may change behavior. The remote HTTP mode uses a static bearer token rather than OAuth, which means browser connectors requiring OAuth need a separate OAuth-capable gateway. Browser access through a GitHub connector can expose the raw Markdown, but may be read-only and does not provide the computed overview, search, or task tools. The project also documents edge cases that its safe-write protections do not cover.