Content
# 🗄️ 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-tag` syntax).
* 🎨 **Obsidian Canvas Support:** Allows the AI to read and "draw" flowcharts, cards, and connecting lines directly inside Obsidian using standard `.canvas` specifications.
* 📅 **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:
```bash
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)
1. Open Cursor and go to **Settings** -> **Features** -> **MCP**.
2. Click **+ Add New MCP Server**.
3. Configure the settings:
* **Name:** `obsidian-brain`
* **Type:** `stdio`
* **Command:**
```bash
C:/path/to/obsidian-brain-mcp/target/release/obsidian-brain-mcp.exe --vault "C:/path/to/your/obsidian/vault"
```
*(Make sure to replace `C:/path/to/obsidian-brain-mcp` with the actual folder path where you cloned this repository).*
4. 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`
```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
| Tool Name | Parameters | Description |
| :--- | :--- | :--- |
| `list_notes` | None | Recursively lists all markdown notes in the vault (showing paths, titles, and sizes). |
| `read_note` | `path` (string) | Reads the raw text content of a note path. |
| `write_note` | `path` (string), `content` (string) | Creates a new note or completely overwrites an existing note. |
| `append_to_note` | `path` (string), `content` (string) | Appends text content to a note (creates the note if it doesn't exist). |
| `append_to_daily_note`| `content` (string) | Resolves local date and appends content to today's daily note (e.g. `YYYY-MM-DD.md`). |
| `search_notes` | `query` (string) | Keyword-searches all notes (case-insensitive full-text lookup). |
| `search_by_tag` | `tag` (string) | Filters and returns note paths containing the specified tag (YAML or inline `#tag`). |
| `get_backlinks` | `note_name` (string) | Finds all other notes referencing the target note. |
| `get_graph` | None | Compiles nodes and edges of double-bracket relationships. |
| `create_canvas` | `path` (string), `nodes` (array), `edges` (array) | Writes/creates an Obsidian Canvas JSON whiteboard board. |
| `read_canvas` | `path` (string) | Reads a `.canvas` file and formats it into a human-readable outline. |
---
## 🧩 Advanced Usage Examples
### 1. Tag Filtering (`search_by_tag`)
You can tag files inside frontmatter or in the middle of notes:
```markdown
---
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.
* **`nodes` format:** `[{ "id": "node-id", "x": 0, "y": 0, "width": 200, "height": 80, "type": "text"|"file", "text": "optional card content", "file": "optional_note_link.md" }]`
* **`edges` format:** `[{ "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:
```bash
cargo test
```
Run the integration stress tests to check directory-traversal defense, fuzzing, and thread concurrency limits:
```bash
python test_mcp.py
```
