by Piotr1215
Provides secure direct file system access to Obsidian vaults and any markdown‑based note collection, enabling fast search, reading, writing, and metadata extraction via the Model Context Protocol.
Enables agents and tools to interact with local Obsidian vaults (or any folder of markdown notes) without requiring the Obsidian desktop application. The server works directly on the file system, offering a compliant MCP endpoint for secure, high‑performance note operations.
npm install
node src/index.js /path/to/your/vault
The process can be launched through Claude Desktop, other MCP‑compatible clients, or directly via the MCP inspector:
npx @modelcontextprotocol/inspector node src/index.js /path/to/your/vault
search-vault, read-note, write-note, discover-mocs, etc., using standard MCP JSON‑RPC calls.Q: Do I need the Obsidian application installed? A: No. The server reads vault files directly from disk, so it works with plain markdown folders, Foam, and Logseq file‑based graphs.
Q: Can I use this with Logseq database graphs? A: Not currently. Only file‑based Logseq graphs are supported.
Q: How does the server prevent accidental deletion of the wrong note?
A: Deletion is gated by MCP elicitation prompting the user for confirmation (unless OBSIDIAN_MCP_CONFIRM_DELETE=off is set).
Q: What operating systems are supported? A: Any platform that can run Node.js. macOS users may need to grant file‑system permissions for iCloud/Docs folders.
Q: How are large notes handled?
A: read-note caps output near 40 KB and provides a truncated flag with a nextOffset for pagination.
Q: Is the server covered by MCP compliance testing?
A: Yes – a badge in the README indicates full MCP compliance, and detailed specs are in MCP_SPEC_COMPLIANCE.md.
MCP server for Obsidian that provides secure, direct file system access to vault files.
Most existing Obsidian MCP servers rely on the Obsidian REST API plugin, which requires:
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.
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 frontmattertitle:: as the page title, falling back to the file name, with a___b.md read as a/b#[[tag name]] tagsIt skips the copies Logseq keeps under logseq/bak/ and logseq/version-files/, as Logseq does.
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!npm install
# Replace /home/decoder/dev/obsidian/decoder with your vault path
npx @modelcontextprotocol/inspector node src/index.js /home/decoder/dev/obsidian/decoder
The inspector will open at http://localhost:5173
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage report
npm run test:coverage
# Run tests with coverage and check thresholds
npm run coverage
# Run mutation testing (all files)
npm run test:mutation
# Run mutation testing (pagination code only - faster)
npm run test:mutation-pagination
To add this server to Claude Desktop, use the Claude CLI:
# Clone this repository
git clone https://github.com/Piotr1215/mcp-obsidian.git
cd mcp-obsidian
# Install dependencies
npm install
# Add to Claude (replace /path/to/your/vault with your Obsidian vault path)
claude mcp add obsidian -s user -- node /path/to/mcp-obsidian/src/index.js /path/to/your/vault
For example, if you cloned the repo to ~/dev/mcp-obsidian and your vault is at ~/Documents/ObsidianVault:
claude mcp add obsidian -s user -- node ~/dev/mcp-obsidian/src/index.js ~/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:
claude mcp list
You should see obsidian in the list of available MCP servers.
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.
Search for content across all notes in your vault.
Features:
title:term, content:term, tag:term"exact phrase"(term1 OR term2) AND term3Context Options:
includeContext (default: true) - Show surrounding linescontextLines (default: 2) - Number of lines before/after match (0-10)Examples:
readme AND install - Find notes containing both wordstitle:setup OR tag:documentation - Find by title or tag"getting started" -deprecated - Exact phrase, excluding deprecated(python OR javascript) AND tutorial - Complex queries with groupingExample Output with Context:
{
"files": [{
"path": "notes/dotfiles.md",
"matchCount": 3,
"matches": [{
"line": 42,
"content": "Managing my dotfiles with stow",
"context": {
"highlighted": "Managing my **dotfiles** with stow"
}
}]
}],
"totalMatches": 43,
"fileCount": 15
}
Search for notes by title: the first H1 (# Title), else a title property (YAML title: or Logseq title::), else the file name.
limit (default 100, max 500) and offset for pagingList all markdown files in your vault or a specific directory.
Every tool returns structuredContent matching its output schema, and the text block is exactly JSON.stringify(structuredContent). Paged results carry pagination.nextOffset (null on the last page). Failures return isError: true with a message that ends in a next step; only an unknown tool or a malformed request is a JSON-RPC error. Read tools are annotated readOnlyHint: true.
Read the content of a specific note. Output is capped near 40,000 characters; a longer note comes back with truncated: true and a nextOffset to pass as the optional offset argument.
bitwarden-cli.md) and the server finds it anywhere in the vaultNotes/projects/bitwarden-cli.md)Create or update a note with new content.
Delete a note from your vault. Permanent, there is no trash.
Clients that support MCP elicitation are asked to confirm first, and the prompt shows the note's size, modification date and first line, read off disk rather than taken from the caller's argument. Refusing keeps the note and the tool reports that it did not delete. A decline, a cancel, a timeout and a dead transport all count as a refusal.
Some clients advertise elicitation and then answer it themselves without showing anyone. Codex 0.153.4 returns a decline in about 10ms on its programmatic tool path. The note is kept either way, and the tool says the client answered rather than blaming you for a prompt you never saw.
Clients that do not advertise elicitation delete without a prompt, as before.
Set OBSIDIAN_MCP_CONFIRM_DELETE=off to turn the prompt off for clients that
do.
Add content to an existing note without overwriting it, creating the note if it
is absent. write-note replaces the whole file; this one does not.
section appends under a specific heading rather than at the endensureNewline (default true) keeps the appended block from running into the
previous lineFind notes containing specific tags.
tags:: properties, inline #tags, and #[[multi word]] tagsGet metadata for one or all notes without reading full content.
⭐ RECOMMENDED: Start here! Discover MOCs (Maps of Content) to understand your vault's knowledge structure.
Maps of Content are organizational hub notes (tagged with #moc) that link to related content. They were pioneered by Nick Milo as a flexible alternative to rigid folder structures.
Features:
limit (default 50, max 200) and offset for pagingWhy use MOCs?
Example Output:
Found 10 MOCs
📚 Vault Index (24 linked notes)
Path: 00-INDEX.md
Links: Work-MOC, AI-MOC, Development-MOC, DevOps-MOC, Tools-MOC, Personal-MOC, Homelab-MOC, MCP-Framework-MOC
🔗 Links to MOCs: Work-MOC, AI-MOC, Development-MOC, DevOps-MOC, Tools-MOC, Personal-MOC, Homelab-MOC, MCP-Framework-MOC
📚 AI-MOC (61 linked notes)
Path: _mocs/AI-MOC.md
Links: chatgpt, ollama, langchain, aider, gp-nvim, MCP-Framework-MOC, ...
🔗 Links to MOCs: MCP-Framework-MOC, Development-MOC, DevOps-MOC, Tools-MOC, Work-MOC, 00-INDEX
This tool enables agents to understand your knowledge graph structure instantly, making navigation ~10x faster than blind keyword searching.
This server implements comprehensive security measures:
.md files can be accesseddelete-note asks the user over MCP elicitation, so the go-ahead comes from a person rather than from an argument the model composed. Path validation stops a traversal but not a deletion of the wrong note inside the vault; this is what covers that.See MCP_SPEC_COMPLIANCE.md for detailed compliance information.
npm testnpm run coveragePlease log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by modelcontextprotocol
A basic implementation of persistent memory using a local knowledge graph. This lets Claude remember information about the user across chats.
by topoteretes
Provides dynamic memory for AI agents through modular ECL (Extract, Cognify, Load) pipelines, enabling seamless integration with graph and vector stores using minimal code.
by basicmachines-co
Enables persistent, local‑first knowledge management by allowing LLMs to read and write Markdown files during natural conversations, building a traversable knowledge graph that stays under the user’s control.
by agentset-ai
Provides an open‑source platform to build, evaluate, and ship production‑ready retrieval‑augmented generation (RAG) and agentic applications, offering end‑to‑end tooling from ingestion to hosting.
by smithery-ai
Provides read and search capabilities for Markdown notes in an Obsidian vault for Claude Desktop and other MCP clients.
by chatmcp
Summarize chat messages by querying a local chat database and returning concise overviews.
by dmayboroda
Provides on‑premises conversational retrieval‑augmented generation (RAG) with configurable Docker containers, supporting fully local execution, ChatGPT‑based custom GPTs, and Anthropic Claude integration.
by qdrant
Provides a Model Context Protocol server that stores and retrieves semantic memories using Qdrant vector search, acting as a semantic memory layer.
by doobidoo
Provides a universal memory service with semantic search, intelligent memory triggers, OAuth‑enabled team collaboration, and multi‑client support for Claude Desktop, Claude Code, VS Code, Cursor and over a dozen AI applications.