Skip to main content
Glama

brain-mcp

MCP server for the Brain Obsidian knowledge base. Provides tools for navigating, searching, creating, and updating notes.

Installation

uv sync

Related MCP server: LifeOS MCP Server

Usage

Run directly

uv run brain-mcp

Configure in Claude Code

claude mcp add brain -- uv run --directory /path/to/brain-mcp brain-mcp

Or add to ~/.claude.json:

{
  "mcpServers": {
    "brain": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/brain-mcp", "brain-mcp"],
      "env": {
        "BRAIN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Configure in Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "brain": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/brain-mcp", "brain-mcp"],
      "env": {
        "BRAIN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Environment Variables

Variable

Description

Default

BRAIN_VAULT_PATH

Absolute path to the Obsidian vault

~/Documents/Projects/Obsidian/Brain

Tools

Tool

Description

brain_search_notes

Full-text search across notes with context snippets

brain_list_notes

List notes in a folder, filterable by frontmatter type

brain_read_note

Read a note by path or title

brain_create_note

Create a new note (defaults to Notes/ per workflow)

brain_update_note

Replace content of an existing note

brain_move_note

Move/promote a note between folders

brain_find_backlinks

Find all notes linking to a given note via wikilinks

brain_get_structure

Vault overview with folder stats and MOC - Home

brain_list_folders

List subdirectories with note counts

Prompts

Prompt

Description

vault_review

Review inbox notes for promotion readiness

kb_update

Generate a KB Update note from a work session

daily_capture

Quick-capture a fleeting note

project_status

Status overview of all active projects

find_related

Map all Brain content related to a topic

Vault Structure

The server expects an Obsidian vault with these canonical folders:

Brain/
├── Notes/           ← Inbox: fleeting notes, KB Updates
├── APIs/            ← External API references
├── Infrastructure/  ← Servers, databases, networking
├── Personal/        ← Personal notes
├── Projects/        ← Active project trackers
├── Repositories/    ← Code repository references
├── Tooling/         ← AI tool configuration
├── Workflows/       ← Standards and processes
└── _Templates/      ← Note templates

Development

# Install with dev dependencies
uv sync --group dev

# Run tests
uv run pytest

# Lint & format
uv run ruff check .
uv run ruff format .

License

MIT

Available Tools

9 tools
brain_create_noteA

Create a new note in the vault.

By default notes are created in Notes/ per the vault workflow standard. Agent-created notes should always go to Notes/ first; promotion happens during manual vault review.

Args: params: Title, content (full markdown with frontmatter), and target folder.

Returns: Confirmation with the path of the created note, or an error if the note already exists.

Inputs: params (required). Returns: result

brain_get_structureA
Read-onlyIdempotent

Get a high-level overview of the vault structure.

Returns the canonical folder layout, note counts per folder, and the contents of MOC - Home for navigation. Use this as a starting point for exploring the vault.

Returns: JSON with folder statistics, total note count, and MOC - Home content.

Inputs: no named parameters. Returns: result

brain_list_foldersA
Read-onlyIdempotent

List subfolders within a vault directory.

Returns immediate subdirectories and their note counts. Useful for exploring the vault hierarchy before reading specific notes.

Args: folder: Optional vault-relative path. Omit for vault root.

Returns: JSON list of subdirectories with note counts.

Inputs: folder. Returns: result

brain_list_notesA
Read-onlyIdempotent

List notes in a vault folder with optional filtering by type.

Returns metadata for notes including path, title, type, updated date, and status. Useful for browsing a folder, reviewing inbox contents, or finding all notes of a specific type.

Args: params: List parameters including folder, note_type filter, recursive flag, limit.

Returns: JSON with note metadata list. Filterable by frontmatter type (moc, project, area, resource, archive).

Inputs: params (required). Returns: result

brain_move_noteA

Move a note from one folder to another (e.g., promote from inbox).

Commonly used to promote notes from Notes/ to their final location in a domain folder (Projects, Infrastructure, APIs, etc.).

Args: params: Source path and destination folder.

Returns: Confirmation with old and new paths, or an error.

Inputs: params (required). Returns: result

brain_read_noteA
Read-onlyIdempotent

Read the full content of a specific note by path or title.

Returns the complete markdown content including frontmatter, plus extracted metadata (type, wikilinks, updated date).

Args: params: Either a vault-relative path or a note title.

Returns: JSON with content, frontmatter metadata, and extracted wikilinks.

Inputs: params (required). Returns: result

brain_search_notesA
Read-onlyIdempotent

Full-text search across the Brain Obsidian vault.

Searches note content for the given query string and returns matching notes with context snippets. Useful for finding notes about a topic, locating references, or discovering related content.

Args: params: Search parameters including query, optional folder scope, and limit.

Returns: JSON with matching notes, each containing path, title, type, match count, and context snippets. Returns an error message if no results found.

Inputs: params (required). Returns: result

brain_update_noteA
Idempotent

Update the content of an existing note.

Replaces the full content. If update_date is True (default), the 'updated' field in frontmatter is set to today's date.

Args: params: Note path or title, new content, and update_date flag.

Returns: Confirmation with the updated path, or an error if not found.

Inputs: params (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap. For example, brain_create_note, brain_read_note, brain_update_note, and brain_move_note handle different aspects of note lifecycle, while brain_list_notes, brain_search_notes, brain_find_backlinks, brain_list_folders, and brain_get_structure serve distinct exploration and discovery functions. The descriptions reinforce these boundaries, making tool selection unambiguous.

    Naming Consistency5/5

    All tools follow a consistent 'brain_verb_noun' pattern using snake_case throughout. The verbs are descriptive and appropriate (e.g., create, find, get, list, move, read, search, update), and the nouns clearly indicate the target resource (e.g., note, backlinks, structure, folders). This uniformity makes the tool set predictable and easy to navigate.

    Tool Count5/5

    With 9 tools, the server is well-scoped for managing an Obsidian vault. It covers core operations like CRUD for notes, vault exploration, and relationship mapping without being overwhelming. Each tool serves a specific, necessary function, and the count aligns with the domain's complexity, avoiding both thin coverage and bloat.

    Completeness5/5

    The tool set provides complete coverage for vault management. It includes full CRUD for notes (create, read, update, move as a form of delete/reorganization), exploration tools (list, search, get structure, list folders), and relationship analysis (find backlinks). There are no obvious gaps; agents can perform all typical workflows from note creation to maintenance and discovery.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      F
      maintenance
      An MCP server that integrates the zk note-taking system with LLMs, enabling users to search, read, create, and manage notes. It provides tools for link analysis, tag management, and complex note queries to interact with local knowledge bases.
      5
      1
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      An MCP server for managing LifeOS Obsidian vaults, enabling AI assistants to create, read, and search notes with YAML compliance and organizational standards.
      1
      GPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that provides read and write access to an Obsidian vault by interacting directly with markdown files on disk. Supports searching, listing, reading, creating, editing, and appending notes without requiring any Obsidian plugins.
      3,713 npm
      ISC
    • F
      license
      C
      quality
      D
      maintenance
      MCP server to query and modify an Obsidian vault or any folder of markdown files. It provides search, tag filtering, backlinks, and CRUD operations on notes, with path traversal protection.
      11
      -