brain-mcp
brain-mcp is an MCP server for managing an Obsidian knowledge base vault, providing tools to navigate, search, create, and organize notes.
Search & Discovery
brain_search_notes: Full-text search across the vault with context snippets, optionally scoped to a folderbrain_list_notes: Browse notes in a folder, filterable by frontmatter type (moc, project, area, resource, archive)brain_find_backlinks: Discover all notes linking to a given note via[[wikilinks]]brain_get_structure: High-level vault overview including folder stats and MOC-Home contentbrain_list_folders: List subdirectories with note counts to explore the vault hierarchy
Note Management
brain_read_note: Retrieve full markdown content and metadata (frontmatter, wikilinks) by path or titlebrain_create_note: Create a new note with title and content, defaulting to theNotes/inbox folderbrain_update_note: Replace a note's full content with automatic frontmatter date stampingbrain_move_note: Move/promote notes between folders (e.g., inbox → Projects or APIs)
Workflow Prompts
Includes prompt-driven workflows: vault_review (inbox triage), kb_update (knowledge base updates), daily_capture (fleeting notes), project_status (project overviews), and find_related (content mapping).
Provides tools for navigating, searching, and managing notes within an Obsidian vault, including capabilities for full-text search, note creation and updates, backlink discovery, and folder structure management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@brain-mcp search my vault for notes about artificial intelligence"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
brain-mcp
MCP server for the Brain Obsidian knowledge base. Provides tools for navigating, searching, creating, and updating notes.
Installation
uv syncRelated MCP server: LifeOS MCP Server
Usage
Run directly
uv run brain-mcpConfigure in Claude Code
claude mcp add brain -- uv run --directory /path/to/brain-mcp brain-mcpOr 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 |
| Absolute path to the Obsidian vault |
|
Tools
Tool | Description |
| Full-text search across notes with context snippets |
| List notes in a folder, filterable by frontmatter type |
| Read a note by path or title |
| Create a new note (defaults to Notes/ per workflow) |
| Replace content of an existing note |
| Move/promote a note between folders |
| Find all notes linking to a given note via wikilinks |
| Vault overview with folder stats and MOC - Home |
| List subdirectories with note counts |
Prompts
Prompt | Description |
| Review inbox notes for promotion readiness |
| Generate a KB Update note from a work session |
| Quick-capture a fleeting note |
| Status overview of all active projects |
| 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 templatesDevelopment
# 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 toolsbrain_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_find_backlinksARead-onlyIdempotent
Find all notes that link to a given note via [[wikilinks]].
Useful for understanding how a note is referenced across the vault, checking if a note is properly linked from MOCs, or mapping relationships between concepts.
Args: params: Title of the note to find backlinks for.
Returns: JSON list of notes that contain [[title]] wikilinks.
Inputs: params (required). Returns: result
brain_get_structureARead-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_foldersARead-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_notesARead-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_noteARead-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_notesARead-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_noteAIdempotent
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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
An MCP server that used to create notes
Related MCP Servers
- AlicenseCqualityFmaintenanceAn 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.51MIT
- AlicenseNot gradedqualityFmaintenanceAn MCP server for managing LifeOS Obsidian vaults, enabling AI assistants to create, read, and search notes with YAML compliance and organizational standards.1GPL 3.0
- AlicenseNot gradedqualityDmaintenanceMCP 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 npmISC
- FlicenseCqualityDmaintenanceMCP 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-