# Big Brain [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/jzhao234/big-brain  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/big-brain

## Description
Plain-markdown second brain for you and your AI: notes, projects, tasks, search, links.

## Tools
Capabilities this server exposes over MCP:

- **brain_overview** — Orient: active projects, due/overdue tasks, inbox, recent notes
- **search_notes** — Full-text search with type/tag/folder/status filters
- **read_note** — Read by path, title, or alias; browse by folder/type/tag
- **create_note** — Write notes (append is the safe default)
- **update_frontmatter** — Metadata changes; non-destructive delete
- **capture** — Quick capture to inbox
- **daily_note** — Daily notes and timestamped work journal
- **list_projects** — Project lifecycle
- **list_tasks** — Checkbox tasks across the vault; `update_task` reschedules, reprioritizes, rewords, reopens, or cancels one in place
- **note_links** — Outgoing links + backlinks for a note
- **related_notes** — Related notes with reasons: links, co-citations, rare shared tags, title mentions, semantic similarity
- **list_tags** — Tag census; broken links, frontmatter that doesn't parse, stale projects, bloated/duplicate notes, overdue tasks

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "big-brain": {
    "command": "npx",
    "args": ["-y","@jzhao234/big-brain"],
    "env": {
      "BIG_BRAIN_VAULT": "",
      "BIG_BRAIN_MCP_TOKEN": "",
      "BIG_BRAIN_MCP_ALLOWED_ORIGINS": ""
    }
  }
}
```

**Requires environment variables:** `BIG_BRAIN_VAULT`, `BIG_BRAIN_MCP_TOKEN`, `BIG_BRAIN_MCP_ALLOWED_ORIGINS` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/big-brain/readme_