Obsidian MCP Server

This project is a high-performance Model Context Protocol server for Obsidian vaults. It gives AI assistants like Claude, Gemini, and Cursor ability to manage your Obsidian vault programmatically. It provides 28 tools organized into categories: read, write, edit, frontmatter, tags, links, graph analysis, and organization.

Key design principles:

Simple setup. Works directly with vault files on disk. No Obsidian plugins, no REST API, no Obsidian running in the background.
Performance. In-memory cache + real-time file watching (watchdog) enables speedy 0(1) note lookups.
Flexible. 28 tools covering reading, writing, line-by-line editing, bulk editing, graph analysis, and more.
Safety. Path traversal protection, atomic bulk operations with rollback, comprehensive test suite (139 tests).

This server is compatible with any MCP client: Claude, Gemini, Cursor, or any applications that support the MCP protocol.

Tools

| Category | Tool | Description | |---|---|---| | Read | list_notes | List all notes in the vault (paginated) | | Read | read_note_by_name | Read a note by name (no .md extension needed) | | Read | search_notes | Full-text search with regex support, path filtering, and pagination | | Read | get_vault_stats | Vault-wide statistics (note count, total links, folder breakdown) | | Read | recent_notes | Notes modified within the last N days | | Write | create_note | Create a new note, optionally in a subfolder | | Write | update_note | Replace a note's entire content | | Write | append_to_note | Append content to the end of a note | | Write | delete_note | Delete a note (requires confirmation flag) | | Edit | read_note_lines | Read a note with line numbers (supports ranges) | | Edit | insert_lines | Insert content after a specific line | | Edit | replace_lines | Replace a range of lines | | Edit | delete_lines | Delete a range of lines | | Edit | bulk_edit | Apply multiple edits across multiple notes atomically, with automatic rollback on failure | | Frontmatter | get_frontmatter | Read all YAML frontmatter or a specific property | | Frontmatter | set_frontmatter | Set a frontmatter property (auto-detects types: lists, ints, bools) | | Frontmatter | delete_frontmatter | Remove a frontmatter property | | Tags | list_tags | All tags across the vault with occurrence counts (frontmatter + inline #hashtags) | | Tags | search_by_tag | Find notes by tag (case-insensitive) | | Links | get_note_links | Extract all WikiLinks from a note | | Links | validate_wikilinks | Check which links in a note point to existing vs. missing notes | | Graph Analysis | vault_graph | Vault-wide link structure summary, or per-note analysis with related note suggestions | | Graph Analysis | find_orphans | Notes with zero connections (no incoming or outgoing links) | | Graph Analysis | find_hubs | Most connected notes, ranked by total link count | | Graph Analysis | find_backlinks | All notes linking to a given note | | Organization | move_note | Move a note to a different folder with automatic backlink updates across the vault | | Organization | find_folder | Search for folders by name or partial match | | Organization | create_folder | Create a new folder |

Setup

Prerequisites

Python 3.10+
An Obsidian vault

Install

Clone the repo and set up a Python virtual environment:

git clone https://github.com/faisalhossainnyc/obsidian-mcp-server.git
cd obsidian-mcp-server
python -m venv venv

Activate the virtual environment:

macOS/Linux: source venv/bin/activate
Windows: venv\Scripts\activate

Then install dependencies:

pip install -r requirements.txt

Configure

Copy the example environment file and set your vault path:

cp .env.example .env

Edit .env and set VAULT_PATH to your vault directory (replace you with your actual username and adjust the path as needed):

macOS: VAULT_PATH="/Users/you/Documents/My Obsidian Vault"
Linux: VAULT_PATH="/home/you/Documents/My Obsidian Vault"
Windows: VAULT_PATH="C:\Users\you\Documents\My Obsidian Vault"

Start the Server

All MCP clients (Claude Desktop, Cursor, Gemini CLI, etc.) launch the server process for you based on the config below, so you don't need to start it manually. The command field in the config tells the client how to start it.

If you want to run the server manually (e.g., to test it or debug):

source venv/bin/activate        # Windows: venv\Scripts\activate
python -m src.server

You should see output confirming the vault cache has loaded and the server is listening.

Connect to an MCP Client

This server uses the standard mcpServers configuration format supported by all major MCP clients. Add the following to your client's config file, replacing the three placeholders with your actual paths:

command — full path to the Python binary inside your venv (e.g. /Users/you/Projects/obsidian-mcp-server/venv/bin/python on macOS/Linux, or C:\Projects\obsidian-mcp-server\venv\Scripts\python.exe on Windows)
cwd — full path to the cloned repo folder (e.g. /Users/you/Projects/obsidian-mcp-server)
VAULT_PATH — full path to your Obsidian vault folder

{
  "mcpServers": {
    "obsidian": {
      "command": "/path/to/obsidian-mcp-server/venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/obsidian-mcp-server",
      "env": {
        "VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Find your config file based on your client:

| Client | Config File | |---|---| | Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Desktop (Linux) | ~/.config/Claude/claude_desktop_config.json | | Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json | | Gemini CLI | ~/.gemini/settings.json | | Cursor | .cursor/mcp.json in your project root | | Claude Code | ~/.claude/claude_code_config.json |

This server implements the Model Context Protocol (MCP), an open standard adopted by Claude, Gemini CLI, ChatGPT, Cursor, VS Code, and more. If your client isn't listed above, check its documentation for the MCP config file location. The JSON format above should work universally.

Architecture

src/
├── server.py          # Entry point — initializes FastMCP + vault cache, registers tools
├── cache.py           # VaultCache: in-memory index with watchdog file watcher (O(1) lookups)
├── utils.py           # Shared utilities: safe_resolve(), read_note(), extract_wikilinks()
└── tools/
    ├── read.py        # 5 tools — list, read, search, stats, recent
    ├── write.py       # 4 tools — create, update, append, delete
    ├── edit.py        # 5 tools — line-level editing with bulk edit + rollback
    ├── frontmatter.py # 3 tools — YAML frontmatter get/set/delete
    ├── tags.py        # 2 tools — tag listing and search
    ├── links.py       # 2 tools — WikiLink extraction and validation
    ├── graph.py       # 4 tools — vault graph analysis (orphans, hubs, backlinks)
    ├── move.py        # 1 tool  — move with backlink updates
    └── folders.py     # 2 tools — folder search and creation

On startup VaultCache builds an in-memory {name → Path} index of every .md file in the vault. A watchdog file observer keeps this index in sync as files are created, deleted, moved, or renamed. every tool call does an O(1) dict lookup instead of scanning the filesystem.

All path-accepting tools use safe_resolve() to prevent path traversal attacks (e.g., ../../etc/passwd is rejected).

The bulk_edit tool reads all target files into memory before applying changes. If any write fails mid-operation, it restores every file from the in-memory backup with no partial writes.

Running Tests

./run_tests.sh

Or directly:

PYTHONPATH=. python -m pytest tests/ -v

The test suite uses a temporary vault fixture that rebuilds from scratch before each test, so tests are fully isolated and don't touch your real vault.

License

MIT

Obsidian MCP Server