🗄️ Obsidian-Brain-MCP (Rust)
An ultra-fast, lightweight Model Context Protocol (MCP) server written in Rust that allows AI Agents (like Cursor, Claude Desktop, Claude Code, and Antigravity) to safely read, search, compile relationships, and interact with local Obsidian knowledge vaults over standard input/output (stdio) channels.
⚡ Why Rust?
- Zero Latency: Starts up in milliseconds and runs native code directly.
- Minimal RAM Footprint: Uses less than 15MB of RAM (Node.js servers usually require over 80MB).
- Zero Dependencies to Run: Compiled into a single native binary. No Node.js, Python, or npm setups required on target systems.
🚀 Key Features
- 🔒 Lexical Path Normalization: Built-in protection against directory traversal attacks (LFI) to ensure AI agents can never escape the vault boundaries.
- 🏷️ Smart Tags Indexing: Searches vault notes by tags (supports both YAML frontmatter metadata and inline
#tag/sub-tagsyntax). - 🎨 Obsidian Canvas Support: Allows the AI to read and "draw" flowcharts, cards, and connecting lines directly inside Obsidian using standard
.canvasspecifications. - 📅 Daily Notes Routing: Instantly logs entries or updates to today's local note (e.g.
YYYY-MM-DD.md) automatically mapping local times. - 🕸️ Backlinks & Graph Compilation: Creates full network diagrams mapping node connections and link edges.
⚙️ Quick Start
1. Build the Binary
Clone the repository and compile the optimized release binary:
cargo build --release
The compiled binary will be created at:
- Windows:
target/release/obsidian-brain-mcp.exe - macOS / Linux:
target/release/obsidian-brain-mcp
🔌 Connecting to LLM Clients
1. Cursor IDE (Setup Guide)
- Open Cursor and go to Settings -> Features -> MCP.
- Click + Add New MCP Server.
- Configure the settings:
- Name:
obsidian-brain - Type:
stdio - Command:
(Make sure to replaceC:/path/to/obsidian-brain-mcp/target/release/obsidian-brain-mcp.exe --vault "C:/path/to/your/obsidian/vault"C:/path/to/obsidian-brain-mcpwith the actual folder path where you cloned this repository).
- Name:
- Click Save. The server status indicator will turn green!
2. Claude Desktop (Setup Guide)
Add this configuration snippet to your Claude Desktop config file:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"obsidian-brain": {
"command": "C:/path/to/obsidian-brain-mcp/target/release/obsidian-brain-mcp.exe",
"args": [
"--vault",
"C:/path/to/your/obsidian/vault"
]
}
}
}
🛠️ Exposed MCP Tools Reference
🧩 Advanced Usage Examples
1. Tag Filtering (search_by_tag)
You can tag files inside frontmatter or in the middle of notes:
---
tags: [ai, agent]
---
# Setup
This is an #obsidian/mcp server node.
Calling search_by_tag(tag: "ai") or search_by_tag(tag: "#obsidian/mcp") returns the file path of this note instantly.
2. Canvas Operations (create_canvas)
Create diagrams programmatically using standard parameters.
nodesformat:[{ "id": "node-id", "x": 0, "y": 0, "width": 200, "height": 80, "type": "text"|"file", "text": "optional card content", "file": "optional_note_link.md" }]edgesformat:[{ "id": "edge-id", "fromNode": "source-id", "fromSide": "right", "toNode": "target-id", "toSide": "left" }]
🧪 Development & Testing
Run the built-in unit tests to verify parser and path safety patterns:
cargo test
Run the integration stress tests to check directory-traversal defense, fuzzing, and thread concurrency limits:
python test_mcp.py