Vault MCP
Lets an AI assistant search and read a folder of Markdown notes such as an Obsidian vault, list pages and titles, read individual pages, run word-based full-text search with matching lines, and report broken [[wikilinks]] (handling aliases, headings, and ignoring links in code blocks). Read-only: it cannot create, modify, or delete notes and refuses any path outside the vault.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Vault MCP search my notes for life cycle assessment"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
vault-mcp
A small, read-only MCP server that lets an AI assistant
(Claude Code, Claude Desktop or any MCP client) search and read a folder of Markdown notes,
such as an Obsidian vault, and list its broken [[wikilinks]]. It cannot change, create or
delete anything, and it refuses every path that leads outside the folder.
It ships with a toy vault of 21 notes on basic energy and life cycle assessment (LCA) concepts, written for this repository, so it runs without any private notes.
Why read-only
MCP is a standard plug between an AI app and tools you write: the app starts the server, asks it which tools it has, and calls them when a question needs them. That makes the server the place where safety is decided. A notes folder often sits next to things the assistant should never see or touch, so this server:
offers only four tools, all marked
readOnlyHint: true, and has no code path that writes;accepts only paths relative to the vault and refuses
.., absolute paths (POSIX, drive letters, UNC),~, null bytes, symlinks and Windows junctions, and non-.mdfiles;never follows symlinked folders when listing or searching.
Related MCP server: vault-mcp-server
Tools
Tool | What it returns |
| Every |
| The full text of one page |
| Pages containing every word of the query, ranked by hits, with up to 3 matching lines each |
| Each |
Run
Python 3.11 or newer.
pip install -e ".[test]"
vault-mcp --vault path/to/your/notesWithout --vault (or $VAULT_ROOT) it serves the bundled toy-vault/.
Add it to Claude Code (run from the repository folder):
claude mcp add vault -- vault-mcp --vault ./toy-vaultFor Claude Desktop, add an entry under mcpServers in claude_desktop_config.json with
"command": "vault-mcp" and "args": ["--vault", "/absolute/path/to/notes"].
Tests
pytest -rs43 tests. tests/test_vault.py has 33: 6 for normal use, 19 path refusals, 6 symlink and
junction cases, 2 write checks. tests/test_server.py has 10 end-to-end cases through a real
MCP client connected in-process. On the development machine (Windows 11, Python 3.13, mcp 2.3.0) the
result was 40 passed, 3 skipped.
python verify.py runs everything in about 6 seconds: a compile check, the tests, then a real
run that starts the server as a subprocess over stdio on the toy vault and compares its
broken_links output with the known-good copy in verify-features/expected_broken_links.json.
It ends with verify: PASS or verify: FAIL at <step>: <reason>. verify-features/ describes
what each check covers. The 3 skipped tests create real symlinks, which Windows
allows only with admin rights or Developer Mode. Their logic is still covered on Windows by a
junction test and a test that fakes a symlink on one path part; the GitHub Actions workflow runs
the full set on Ubuntu and Windows.
The write checks are: the tool list is exactly the four read tools, all marked read-only; calls
to write_page, delete_page, create_page and edit_page fail; every file in the vault has
the same SHA-256 hash before and after calling every tool; and the source contains no
file-writing call.
Trying it from Claude Code
eval/questions.md holds 10 questions with known answers in the toy vault, plus a broken-link
check and an escape attempt. They were run once with Claude Code in print mode
(claude -p, model sonnet, 2026-11-19), with only this server's four tools allowed and the
built-in file tools blocked, so every answer had to come through the server.
Check | Result |
Questions answered correctly (scored by hand against the notes) | 10 / 10 |
Of those, questions with no answer in the vault, correctly answered "not in the vault" | 2 / 2 |
Planted broken links found | 7 / 7, 0 false positives |
Link inside a code block (should be ignored) | ignored |
| refused: |
Cost and time of the run, as reported by Claude Code | 0.195 USD, 17 turns, 19 s |
The planted broken links are listed in tests/test_vault.py (PLANTED), and a test checks that
broken_links() returns exactly that set.
What failed or is weak
One run of 10 questions is a smoke test, not an evaluation. The questions were written by the same author as the notes, so they are easier than real use.
Question 8 ("which pages link to District Heating?") was answered by text search. There is no backlinks tool, so a page that mentions the name without linking would be counted too.
First attempt at the source check banned the word
symlinkand failed on the server's own docstring; it now bansos.symlinkonly.Deleting the
..rule on purpose did not make any test fail, because the second check (resolve the path, then confirm it is inside the vault) still blocked every escape. Good for safety, but the..rule itself was untested. A test now asks forlca/../index.md, which stays inside the vault and must still be refused.
Limits
Search is plain word matching, no stemming or ranking beyond hit counts. Fine for a few hundred notes, not for tens of thousands.
Pages are read up to 200 kB each.
Link matching is by file name or vault-relative path, case-insensitive, like Obsidian's default. Links to images and other attachments are reported as broken.
Read-only is enforced by what the code does, not by the operating system. For a hard guarantee, also run the server as a user who has read-only rights on the folder.
Not tested on macOS. Claude Desktop was not tried, only Claude Code.
Licence
MIT. The toy vault is written for this repository and may be reused freely.
Available Tools
4 toolsbroken_linksARead-onlyIdempotent
List [[wikilinks]] that point to a page that does not exist in the vault.
Links inside code blocks and inline code are ignored. Each result gives the page the link is on, the line number and the missing target.
Inputs: no named parameters. Returns: result
list_pagesBRead-onlyIdempotent
List every Markdown page in the vault with its title.
Args: folder: Optional subfolder to list, relative to the vault root (for example "lca").
Inputs: folder. Returns: result
read_pageARead-onlyIdempotent
Return the full Markdown text of one page.
Args: path: Path relative to the vault root, as returned by list_pages (for example "lca/Allocation.md").
Inputs: path (required). Returns: result
searchARead-onlyIdempotent
Find pages containing all the words in the query (case-insensitive).
Results are ranked by how often the words occur and show up to three matching lines.
Args: query: One or more words; a page must contain every word to match. limit: Maximum number of pages to return (1 to 50).
Inputs: query (required), limit. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: listing pages, reading a page, full-text searching, and finding broken wikilinks. Although list_pages and search both help locate pages, one is structural and the other content-based, so an agent can easily choose between them.
Two tools follow a verb_noun pattern (list_pages, read_page), but 'search' is a bare verb and 'broken_links' is a noun phrase. The mixed conventions are still readable, but they prevent a fully predictable pattern.
Four tools are well-scoped for a read-only Markdown vault interface. Each tool covers a distinct operation and none feels redundant or extraneous.
The surface covers listing, reading, searching, and link validation, but there are no write operations such as create_page, update_page, or delete_page. If the vault is intended to be editable, this is a notable gap; if strictly read-only, it is closer to complete.
Maintenance
Related MCP Connectors
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Related MCP Servers
- AlicenseAqualityCmaintenanceA filesystem-based MCP server for Obsidian vaults that enables LLMs to browse, search, read, write, and edit Markdown notes directly on disk without requiring Obsidian to be running.61CeCILL-B Free Software Agreement
- FlicenseCqualityDmaintenanceMCP server to query and modify an Obsidian vault or any folder of markdown files. It provides search, tag filtering, backlinks, and CRUD operations on notes, with path traversal protection.11-
- FlicenseAqualityDmaintenanceMCP server that exposes an Obsidian vault to AI assistants, enabling them to list, read, write, search, and delete notes via the Local REST API.7-
- AlicenseNot gradedqualityDmaintenanceMCP server for browsing Obsidian-compatible Markdown vaults, searching notes, viewing backlinks and knowledge graphs, and adding selected content to chat context.9 npmMIT