obsidian-mcp
Provides read and write access to a local Obsidian vault, enabling note creation, editing, deletion, full-text search, backlink graph, vault health analysis, and policy enforcement.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
obsidian-mcp
MCP server exposing an Obsidian vault to LLM clients (Claude, Cursor, Continue, ...).
Why?
A Second Brain should be queryable by AI agents — without shipping your data to a third-party API. This server gives any MCP-compatible client read and write access to a local Obsidian vault via the Model Context Protocol.
Key differentiators (vs. existing Obsidian MCP servers):
Headless & filesystem-native — no Obsidian desktop app required, container-ready
Structured output schemas on every tool — LLMs know exactly what to expect
Vault graph analytics — wikilink graph, orphan detection, outlink tracing
Vault health check — automated quality scoring (broken links, untagged, TODOs, duplicates)
Policy enforcement — write log, raw/ immutability, agent locking, and wiki-index upkeep enforced at the filesystem choke point, not left to client discipline
Ranked full-text search — Whoosh-backed index with Lucene-style query syntax (fields, booleans, phrases, wildcards, fuzzy, ranges, did-you-mean)
AI-optimized tool descriptions — 5-element docstring pattern with actionable error messages
Related MCP server: Obsidian Vault API
Features
Read and Search notes (full-text, case-insensitive)
Create, Update, Delete notes with proper YAML frontmatter
Append to notes (upsert), patch sections under headings
Frontmatter and tag management (get/set/delete, dedup, case-insensitive)
Daily notes (YYYY-MM-DD format with date validation)
Search & replace (literal + regex with capture groups)
Backlink graph traversal (wikilinks)
Vault structure as a JSON resource
Path traversal protection on all entry points (vault sandbox)
Tag extraction (frontmatter + inline tags)
Structured output schemas for every MCP tool (29/29)
Vault write policies: write log (per-actor shards in
.vault-write-log.d/, legacy.vault-write-log.jsonlas fallback/opt-out), raw/ immutability, scope locks per agent (.vault-lock.d/, legacy.vault-lock), wiki/index.json upkeep, link checking. The server owns this bookkeeping: clients never append log lines themselves; every write tool takes an optionalrelated_to(work-item uid) that lands in the log linearchive_note: archive-instead-of-delete with backlink reporting
Attachments: original files (PDF, Office, images, mails, archives) filed under
raw/assets/<YYYY>/<MM>/with a companion note, SHA-256 deduplication and a type allow-list that always refuses executablesIncremental Whoosh full-text index (BM25, stemmed, field queries, fuzzy, did-you-mean) with configurable index directory
Vault graph analytics (nodes, edges, stats, broken links)
Vault health scoring (0–100 with actionable issue report)
Documentation
Document | Description |
Architecture walkthrough, code tour, extension guide, Docker/K8s deployment | |
Optional hybrid search (Whoosh + Qdrant vectors), setup and design | |
Best practices for AI-optimized MCP tool descriptions | |
Notable changes with added, fixed, and changed items |
Quick Start
pip install -e .
# Point at your real vault
export OBSIDIAN_VAULT_ROOT=/path/to/your/obsidian/vault
# Run (stdio transport)
obsidian-mcpOr use the bundled mock vault (no config needed):
obsidian-mcp # uses examples/mock-vault/Client Integration
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"obsidian": {
"command": "obsidian-mcp",
"env": {
"OBSIDIAN_VAULT_ROOT": "/path/to/your/vault"
}
}
}
}Cursor
Cursor supports MCP from version 0.42+. Configure in ~/.cursor/mcp.json (same format as Claude Desktop).
Any other MCP client
The server runs on stdio. Register it with your client's standard MCP configuration
(command: obsidian-mcp or python3 -m obsidian_mcp.server, env: OBSIDIAN_VAULT_ROOT).
Tools (29)
Tool | Description |
| Read a note (title, tags, metadata, content) |
| Full-text search across title and body |
| List notes, optionally scoped to a folder |
| List note paths only (lightweight) |
| Create a note with frontmatter |
| Update body (frontmatter preserved) |
| Permanently delete a note |
| Append content (create if missing) |
| Get/set/delete one frontmatter key, or several in one write ( |
| Add/remove/list tags |
| Insert/prepend/replace under a heading |
| Read/append daily notes (YYYY-MM-DD.md) |
| Find/replace in note body |
| Find notes linking via wikilinks |
| Full vault link graph (nodes, edges, stats) |
| Notes with no incoming or outgoing wikilinks |
| Outgoing wikilinks from a note |
| Health score + issue report (0–100) |
| Move note to archive folder; report backlinks |
| Lock a folder or note for this agent (other agents' writes there are refused) |
| Extend own active locks |
| Release own locks |
| List all active locks of all agents |
| File an original document under |
| List filed attachments, newest first |
| Metadata of one attachment, optional SHA-256 check |
| Ranked Lucene-style full-text query (fields, fuzzy, ranges) |
| Rebuild the full-text index from all notes |
| Index health: docs indexed vs. vault notes |
Locks: lock_scope writes .vault-lock.d/<actor>.json (one file per agent,
so file sync never merges two writers). While a lock is active, writes of other
agents whose target lies inside the scope are refused with VAULT_LOCK; writes
elsewhere and all reads stay possible. Locks expire on their own after ttl_min
(default 30, max 240). A legacy .vault-lock file in the vault root still locks
the whole vault for 30 minutes after its last change. VAULT_LOCK=0 disables
both.
Attachments: attach_file takes content_base64 (up to
ATTACH_MAX_INLINE_MB, default 10) or source_path, a file already in the vault
such as 00 Inbox/scan.pdf (up to ATTACH_MAX_MB, default 100; moved unless
keep_source). Allowed: pdf, docx, xlsx, pptx, csv, txt, md, msg, eml, png, jpg,
jpeg, gif, webp, svg, zip, 7z, tar.gz. The content must match the extension;
executables, scripts, macro Office files and archives containing them are
refused with ATTACHMENT_TYPE. File and companion note are raw/ and immutable.
Restricted folders (optional): OBSIDIAN_SEARCH_RESTRICTED="05 People,Private"
hides these folders from every search, listing and graph tool (and from
hybrid_search) unless the call sets include_restricted=true. Results then
carry restricted_hidden: true. Reading a note by its path, or listing a
restricted folder by name, stays possible: naming it is an explicit request.
Links into a hidden folder still resolve (no false broken links), but the
graph shows only the link text, not the hidden path. Unset (default): nothing
is hidden.
Index freshness: on start the server reconciles the full-text index with
the files on disk in the background (notes moved or edited by file sync or the
Obsidian editor while it was not running). Processes sharing one index do this
once: a process skips if the index was reconciled within
OBSIDIAN_INDEX_RECONCILE_MAX_AGE seconds (default 900).
OBSIDIAN_INDEX_RECONCILE=0 turns it off.
Optional, with pip install 'obsidian-mcp[semantic]' and OBSIDIAN_SEMANTIC=1
(see Semantic Search):
Tool | Description |
| Find notes by meaning and words, fused ranking |
| Catch up the vector index; report its status |
Plugins
Optional extensions are installed as Python packages with an entry point in the
group obsidian_mcp.plugins and enabled by name, e.g. OBSIDIAN_PLUGINS=oversight
(comma-separated). Nothing is loaded without the variable. A plugin's
register(api) can add tools (api.add_tool(fn), core tool names are reserved) and
subscribe to events (api.on(event, handler)):
Event | Keyword arguments |
|
|
|
|
|
|
|
|
Plugins are fail-open: an error while loading or in a handler goes to stderr and never fails a write or a tool call. They run in the server process with the server's rights, so only enable plugins you trust. Example: the sensor of agent-oversight reports the server's heartbeat and every refusal or tool error as oversight signals.
Prompts (3)
Prompt | Arguments | Description |
|
| Review daily notes and project context before starting work |
|
| Document accomplishments, decisions, and open questions |
|
| Review and update a specific project's documentation |
Resources (1)
URI | Description |
| Folder/file tree of the vault as JSON |
Architecture
MCP Client ←—MCP stdio—→ obsidian-mcp server → vault.py → Obsidian Vault
(Claude/Cursor/...) (22 tools + 3 prompts) (filesystem) (*.md + YAML)
+ 1 resource │
policies.py ←——————┘ (write log, raw lock,
wiki index, link check)
search_index.py → Whoosh index (BM25)Design decisions:
Filesystem-native instead of REST API: headless, containerizable, no app dependency
Path traversal protection at all entry points (
_resolve(),_resolve_folder())Singleton pattern for Vault instance (testable via
set_vault())Pydantic BaseModel return types for
outputSchemaon all 22 tools
Development
pip install -e ".[dev]"
pytest tests/ # 448 tests, all passingCI runs on Python 3.10, 3.11, and 3.12 with pytest + ruff.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables natural language interaction with Obsidian vaults through an MCP server, providing hybrid search, file management, and AI-powered analysis.2-
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to read, write, search, and manage files in an Obsidian vault via MCP over SSE, running standalone without the Obsidian desktop app.2Creative Commons Attribution Non Commercial Share Alike 4.0 International
- FlicenseNot gradedqualityBmaintenanceServes as a unified MCP gateway to an Obsidian vault, enabling AI agents to perform hybrid lexical/vectorial semantic search, explore note graphs, and write through consent-based intent batches with conflict detection.-
- AlicenseAqualityBmaintenanceEnables MCP clients to read, write, search, and manage notes, canvases, kanban boards, and other Obsidian vault content over a network, without requiring the Obsidian desktop app.33MIT