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

Related MCP server: Obsidian MCP Server

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:

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