Piotr1215/mcp-obsidian

MCP server for Obsidian that provides secure, direct file system access to vault files.
Why This Server?
Most existing Obsidian MCP servers rely on the Obsidian REST API plugin, which requires:
- Obsidian to be installed
- Obsidian to be running
- The REST API plugin to be configured
This server instead works directly with Obsidian vault files on disk, making it compatible with setups using obsidian.nvim - a Neovim plugin that provides Obsidian-like features without requiring the Obsidian app.
Logseq and Foam
Any folder of markdown notes works, so the server also reads Foam workspaces and file-based Logseq graphs. Point it at the workspace or graph folder.
| Tool | Version | Status |
|------|---------|--------|
| Foam | any | Supported |
| Logseq file graphs | 0.10.x and earlier | Supported |
| Logseq DB graphs | 2.x | Not supported: pages live in a database, not in markdown files |
For Logseq graphs the server also reads:
- tags:: and other page properties at the top of a page, reported as tags and frontmatter
- title:: as the page title, falling back to the file name, with a___b.md read as a/b
- multi-word #[[tag name]] tags
It skips the copies Logseq keeps under logseq/bak/ and logseq/version-files/, as Logseq does.
Features
- **Direct file system access** to Obsidian vaults - no Obsidian app required
- **Security-first design** with path traversal prevention and input validation
- **High performance** with execution time tracking and resource limits
- **Rich search capabilities** including regex support and tag-based search
- **Metadata support** with frontmatter and inline tag parsing
Recent Updates
🎉 New Features
- **🗺️ MOC Discovery**: New discover-mocs tool provides a high-level map of your vault's knowledge structure by discovering Maps of Content and their relationships. **Start here for 10x faster navigation!**
- **Resource Links**: Search results now include MCP resource links for direct note access
- **Context Snippets in Search Results**: Search results now include surrounding lines for better context understanding
- **Match Highlighting**: Search terms are highlighted with **bold** markers in results
- **Improved Search Result Structure**: Results are now grouped by file with match counts and snippets
Installation
Usage
Testing with MCP Inspector
The inspector will open at http://localhost:5173
Running Tests
Adding to Claude Desktop
To add this server to Claude Desktop, use the Claude CLI:
For example, if you cloned the repo to ~/dev/mcp-obsidian and your vault is at ~/Documents/ObsidianVault:
This will add the server to your Claude configuration file (typically ~/.claude.json or ~/.config/Claude/claude_desktop_config.json).
To verify the installation:
You should see obsidian in the list of available MCP servers.
Vault path
The server expands a leading ~ in the vault path, since MCP clients start it without a shell. It does not expand environment variables such as $HOME.
If the server cannot read the vault, every tool that lists notes returns an error naming the cause instead of an empty result. On macOS, a vault in iCloud Drive, Documents or Desktop needs the app that starts the server, such as Claude or your terminal, to have access under System Settings > Privacy & Security > Files and Folders, or Full Disk Access.
Available Tools
search-vault
Search for content across all notes in your vault.
**Features:**
- Boolean operators: AND, OR, NOT (also supports &&, ||, -)
- Field specifiers: title:term, content:term, tag:term
- Quoted phrases: "exact phrase"
- Grouping with parentheses: (term1 OR term2) AND term3
- Case-sensitive/insensitive search
- **Context snippets**: See surrounding lines for each match
- **Match highlighting**: Search terms are highlighted with **bold**