some-vault-some-mcp
Provides tools for reading, writing, searching, and managing notes, canvases, daily notes, and link graphs in an Obsidian 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., "@some-vault-some-mcp search for notes about machine learning"
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.
some-vault-some-mcp
MCP server that gives AI models read/write access to Obsidian vaults with semantic search, link graph analysis, canvas manipulation, and incremental indexing.
Built on FastMCP + LanceDB. Embeds notes locally with fastembed (nomic-embed-text-v1.5-Q, 768 dims) by default — no server required. Optionally supports Ollama or OpenAI embeddings. Watches the vault filesystem and re-indexes on change.
Warning: This is a hot vibe coded mess, user beware
What it does
Hybrid search - vector similarity (70%) + full-text keyword (30%), with overlap boost
Semantic search - pure embedding-based retrieval
Exact search - literal substring matching, optional case sensitivity and regex
Note CRUD - create, read, append, prepend, move, delete (soft delete to .trash by default)
Frontmatter parsing - YAML extraction, tag collection (frontmatter + inline #hashtags), property filtering
Wikilink graph - backlinks, outlinks, orphan detection, broken link detection, BFS neighbor traversal (depth 1-5)
Canvas CRUD - create, read, add/update/remove nodes and edges, grid auto-layout, dangling edge cleanup
Daily notes - Moment.js-style date formatting, template support, reads Obsidian's daily-notes config
Incremental indexing - filesystem watcher with 2s debounce and SHA-256 content change detection
Atomic writes - temp file + POSIX rename, per-path asyncio locks
Tool overrides - rename or disable any tool via YAML config (per-agent customization)
Related MCP server: Grove
Requirements
Python 3.11+
uv (for
uvx)
Quick start
Add this to your MCP client config (Cursor, Windsurf, Claude Code, etc.):
{
"mcpServers": {
"obsidian-vault": {
"command": "uvx",
"args": ["some-vault-some-mcp", "serve", "--transport", "stdio"],
"env": {
"VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}That's it. uvx installs the package from PyPI on first run and keeps it cached.
For alternative embedding providers, add --from with extras:
{
"command": "uvx",
"args": ["--from", "some-vault-some-mcp[ollama]", "some-vault-some-mcp", "serve", "--transport", "stdio"],
"env": {
"VAULT_PATH": "/path/to/your/obsidian/vault"
}
}Replace [ollama] with [openai] or [gpu] as needed.
SSE mode
If running the server separately (Docker, remote, etc.), use the SSE URL instead:
{
"mcpServers": {
"obsidian-vault": {
"url": "http://localhost:3789/sse"
}
}
}Running directly
VAULT_PATH=/path/to/vault uvx some-vault-some-mcp serveFirst run builds a staged index generation and publishes it only after schema, vector, and full-text validation. Subsequent starts scan content hashes and publish incremental changes through staged generations too, so the last valid generation remains available on failure. Readers hold a cross-process shared lease while materializing results; publication and live cleanup take the exclusive side, so completed databases retain only the active and previous generations without dropping an in-flight reader's table.
CLI flags
some-vault-some-mcp serve [--transport sse|stdio] [--host 127.0.0.1] [--port 3789] [--reindex-force]--reindex-force builds and validates a replacement generation without dropping
the active index first. It is required when embedding dimensions change. The server
also rebuilds automatically (one time) when it detects an index written by an
older storage format.
CLI flags override env vars.
Environment variables
Variable | Default | Notes |
| (required) | Absolute path to Obsidian vault |
|
| Vector index location. Use a trusted absolute path outside the vault and workspace; unsafe locations produce a warning. |
|
|
|
|
| SSE bind address. Defaults to loopback — set |
|
| SSE port |
|
|
|
|
| Any fastembed-supported model. On Apple Silicon, auto-detects and uses the non-quantized variant ( |
| (auto-detected) | Override dimension auto-detection |
|
| Ollama API endpoint (requires |
| Required if provider is | |
| Enables Bearer token auth on SSE transport (constant-time compare; covers | |
|
|
|
|
|
|
| Path to YAML override file |
Docker
docker build -t some-vault-some-mcp .
docker run -p 3789:3789 \
-v /path/to/vault:/opt/vault:ro \
-v /data:/opt/data \
some-vault-some-mcpRuns as non-root user (vault:vault, UID 1000). Index data persists in /opt/data. Vault mounted read-only. Container is self-contained — fastembed runs in-process, no Ollama sidecar needed.
To use Ollama instead: docker run ... -e EMBEDDING_PROVIDER=ollama -e OLLAMA_URL=http://ollama:11434 some-vault-some-mcp
Tools (27)
Search
search
Find notes by text, meaning, or exact string.
Param | Type | Default | Notes |
| string | (required) | Search query text |
| string |
|
|
| int |
| Max results to return |
| string[] |
| Pre-filter by tags |
| string |
| Pre-filter by folder path prefix |
| bool |
| Exact mode only - match case |
Read
get_note
Read a single note with parsed frontmatter and tags.
Param | Type | Default | Notes |
| string | (required) | Vault-relative path to the note. Extension-agnostic — |
list_notes
Enumerate vault notes with optional metadata filters. Index-backed fields (tags, projects, status, area) query LanceDB when available. Frontmatter property filtering scans files directly.
Param | Type | Default | Notes |
| string |
| Filter by folder path prefix |
| string[] |
| Filter by tags (index-backed) |
| string[] |
| Filter by projects (index-backed) |
| string |
| Filter by status field (index-backed) |
| string |
| Filter by area field (index-backed) |
| string |
| Arbitrary frontmatter key to filter on |
| string |
| Value to match for |
| bool |
| Include note content in results |
| int |
| Max results to return |
Write
create_note
Create a new note. Fails if it already exists.
Param | Type | Default | Notes |
| string | (required) | Vault-relative path for the new note |
| string | (required) | Note body text |
| string |
| JSON string of frontmatter fields, e.g. |
append_to_note
Append text to the end of an existing note.
Param | Type | Default | Notes |
| string | (required) | Vault-relative path |
| string | (required) | Text to append |
prepend_to_note
Insert text after frontmatter, before the note body.
Param | Type | Default | Notes |
| string | (required) | Vault-relative path |
| string | (required) | Text to prepend |
update_frontmatter
Merge key-value pairs into YAML frontmatter. Unlisted keys preserved.
Param | Type | Default | Notes |
| string | (required) | Vault-relative path |
| string | (required) | JSON string of key-value pairs, e.g. |
move_note
Move or rename a note. Rewrites wikilinks vault-wide by default. Moves are no-replace operations: an existing distinct destination is never overwritten. Filesystems without the platform's native exclusive-rename capability are rejected rather than falling back to an overwriting rename. A separately named hard-link destination also fails closed because it cannot be removed safely under a concurrent destination replacement.
Param | Type | Default | Notes |
| string | (required) | Current vault-relative path |
| string | (required) | Destination vault-relative path |
| bool |
| Rewrite wikilinks in all referencing notes |
delete_note
Delete a note. Moves to .trash by default; use permanent for hard delete.
Param | Type | Default | Notes |
| string | (required) | Vault-relative path |
| bool |
|
|
Daily notes
get_daily_note
Read today's or a specific date's daily note. Uses Obsidian's daily-notes config for folder and date format. Returns a text message (not an error) if no note exists for the requested date.
Param | Type | Default | Notes |
| string |
| Date string (e.g. |
create_daily_note
Create a daily note for today or a given date. Fails if one exists. Supports {{date}} placeholder in templates.
Param | Type | Default | Notes |
| string |
| Date string. Omit for today |
| string |
| Note body text |
| string |
| Vault-relative path to a template note |
Tags
get_tags
List all unique tags in the vault with per-note usage counts.
Param | Type | Default | Notes |
| string |
|
|
Link graph
get_backlinks
Find notes that link to a given note.
Param | Type | Default | Notes |
| string | (required) | Vault-relative path of the target note |
get_outlinks
List all outgoing wikilinks from a note. Shows valid, broken, and embed links separately.
Param | Type | Default | Notes |
| string | (required) | Vault-relative path |
find_orphans
Find disconnected notes - no inbound links, no outbound links, or both.
Param | Type | Default | Notes |
| bool |
| Also report notes with no outgoing links |
| int |
| Cap per category |
find_broken_links
Find wikilinks pointing at notes that don't exist.
Param | Type | Default | Notes |
| string |
| Limit scan to a folder |
| int |
| Max broken links to return |
get_graph_neighbors
Walk the link graph outward from a note via BFS.
Param | Type | Default | Notes |
| string | (required) | Starting note path |
| int |
| BFS depth, 1-5 |
| string |
|
|
Canvas
list_canvases
List all .canvas files in the vault.
Param | Type | Default | Notes |
| string |
| Filter by folder path prefix |
read_canvas
Read canvas structure (nodes + edges).
Param | Type | Default | Notes |
| string | (required) | Vault-relative path to .canvas file |
create_canvas
Create a new .canvas file with optional initial nodes/edges. Fails if it already exists.
Param | Type | Default | Notes |
| string | (required) | Vault-relative path for the new canvas |
| string |
| JSON array of node objects, e.g. |
| string |
| JSON array of edge objects |
add_canvas_node
Add a node (text/file/link/group) to a canvas. Position auto-computed via grid layout if omitted.
Param | Type | Default | Notes |
| string | (required) | Path to the canvas |
| string | (required) |
|
| string |
| Text content (for text nodes) |
| string |
| Vault-relative file path (for file nodes). For markdown notes the |
| string |
| URL (for link nodes) |
| string |
| Display label |
| int |
| X position. Auto-placed if omitted |
| int |
| Y position. Auto-placed if omitted |
| int |
| Node width in pixels |
| int |
| Node height in pixels |
| string |
| Obsidian preset |
update_canvas_node
Update any property of an existing canvas node by ID. Only provided fields are changed.
Param | Type | Default | Notes |
| string | (required) | Path to the canvas |
| string | (required) | ID of the node to update |
| int |
| New X position |
| int |
| New Y position |
| int |
| New width |
| int |
| New height |
| string |
| Preset |
| string |
| New text content |
| string |
| New file reference |
| string |
| New URL |
| string |
| New label |
remove_canvas_nodes
Remove nodes by ID. Auto-removes dangling edges.
Param | Type | Default | Notes |
| string | (required) | Path to the canvas |
| string | (required) | JSON array of node ID strings, e.g. |
add_canvas_edge
Add an edge between two canvas nodes with full property support.
Param | Type | Default | Notes |
| string | (required) | Path to the canvas |
| string | (required) | Source node ID |
| string | (required) | Target node ID |
| string |
| Anchor side on source: |
| string |
| Anchor side on target |
| string |
| End style on source side (e.g. |
| string |
| End style on target side |
| string |
| Preset |
| string |
| Edge label text |
update_canvas_edge
Update properties of an existing canvas edge by ID. Only provided fields are changed.
Param | Type | Default | Notes |
| string | (required) | Path to the canvas |
| string | (required) | ID of the edge to update |
| string |
| New source anchor side |
| string |
| New target anchor side |
| string |
| New source end style |
| string |
| New target end style |
| string |
| Preset |
| string |
| New label |
remove_canvas_edges
Remove edges from a canvas by ID.
Param | Type | Default | Notes |
| string | (required) | Path to the canvas |
| string | (required) | JSON array of edge ID strings |
Index management
vault_index_status
Check search index health and statistics, including rebuild progress, degraded fallback serving, pending changes, and the last rebuild error. No arguments.
vault_reindex
Reindex one note incrementally, or build and atomically publish a new generation when the path is omitted.
Param | Type | Default | Notes |
| string |
| Vault-relative path to reindex a single note. Omit for full vault |
MCP resources
obsidian://note/{path}- read a note by pathobsidian://tags- all tagsobsidian://daily- today's daily note
Tool name overrides
When you need to change the tool names and descriotions, a YAML file can be used. Create a YAML file, and set some_vault_some_mcp_OVERRIDES to its path:
tools:
search:
name: "vault_search"
description: "Custom description for this agent"
get_note:
name: "read_note"
disabled:
- get_tags
- find_orphansOverrides apply at registration time. Useful for per-agent tool namespacing or disabling tools an agent shouldn't use if your agent doesn't support tool disabling.
How search works
Hybrid (default) - runs both semantic and FTS (LanceDB full-text search, BM25-style) at 2x requested top_k, normalizes scores, combines with semantic * 0.7 + FTS * 0.3. Results appearing in both get a 1.2x boost. Returns top_k from merged set.
Semantic - embeds the query, runs vector similarity search against LanceDB.
Exact - scans raw vault files for literal substring matches. Not index-backed. Optional case sensitivity.
All search modes accept tag and folder pre-filters. Tags use SQL LIKE against comma-separated tag strings in the index. Folders use path prefix matching.
Chunking
Splits markdown by heading hierarchy first, then by paragraph for oversized sections. Tracks heading breadcrumbs through the split - a chunk under # A / ## B / ### C gets heading field "A > B > C". Metadata header prepended to embedding text: [Title: X | Section: A > B | Tags: foo, bar].
Wikilink resolution
Matches Obsidian's behavior in 4 steps:
Exact relative-path match (case-insensitive)
Path-suffix match (if link contains
/)Basename match with proximity tie-break (deepest shared path prefix with source)
Alias match (frontmatter aliases)
First matching step wins.
Security boundaries
Tool paths are validated against the vault root and reject
../, null bytes, and static symlink escapes. These pathname checks do not close the concurrent symlink-swap race described as SR-04 inSECURITY_REVIEW.md..obsidian,.git,.trashdenied at the tool boundary and excluded from indexingAny folder whose name starts with
.(for example.claude/) is skipped by the indexer and by note listings. Add more folder names withVAULT_EXCLUDED_DIRS=external,archiveor with anexcluded_dirs: [external, archive]list in the override file. These folders are hidden, not denied: search, listings, backlinks and link rewrites skip them, but a tool call with the exact path still works.resolve_vault_pathstill denies only.obsidian,.gitand.trash.Optional Bearer token auth on SSE transport
Docker container runs as non-root
Frontmatter normalization rejects recursive aliases, excessive depth, excessive node or scalar-payload expansion, invalid timestamps, non-string mapping keys, and unsupported scalar types. Invalid metadata is discarded while the note body remains indexable.
Index recovery
Full rebuilds retain the previous valid generation. If a newly published index
must be rolled back, stop every server process using that LANCE_DB_PATH, back up
the complete index directory, then swap the active and previous table names in
_index_manifest.json. Write the edited JSON to a sibling temporary file and
atomically replace the manifest; do not edit it in place. Restart the server and
confirm vault_index_status reports the expected file and chunk counts. Keep the
backup until search results have been checked. If either named table is missing or
the manifest is malformed, restore the backup instead of deleting tables manually.
Developing
Setup
git clone https://github.com/russellsch/some_obsidian_some_mcp.git
cd some_obsidian_some_mcp
uv sync # default (fastembed CPU)
uv sync --extra gpu # GPU-accelerated embeddings
uv sync --extra ollama # Ollama provider
uv sync --extra openai # OpenAI providerRunning from source
VAULT_PATH=/path/to/vault uv run some-vault-some-mcp serveTo use a local checkout in your MCP client config instead of the PyPI package:
{
"mcpServers": {
"obsidian-vault": {
"command": "uv",
"args": ["run", "--project", "/path/to/some_obsidian_some_mcp", "some-vault-some-mcp", "serve", "--transport", "stdio"],
"env": {
"VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}Tests
uv run pytest tests/unit # unit tests (fast, no external deps)
uv run pytest tests/integration # integration tests (real LanceDB, may download ~130MB model)
uv run pytest # everythingTest fixtures live in tests/fixtures/vault/.
Releasing
See RELEASING.md.
Available Tools
28 toolsadd_canvas_edgeC
Add an edge between two canvas nodes with full property support.
Inputs: to_node (required), from_node (required), canvas_path (required), color, +5 more.
add_canvas_nodeA
Add a node (text/file/link/group) to a canvas. Auto-layout when position omitted.
Inputs: node_type (required), canvas_path (required), x, y, +7 more.
append_to_noteA
Append text to the end of an existing note. The .md extension is added automatically.
Inputs: path (required), content (required).
create_canvasB
Create a new .canvas file with optional initial nodes/edges.
Inputs: path (required), edges, nodes.
create_daily_noteA
Create a daily note for today or a given date. Fails if one exists.
Inputs: date, content, template_path.
create_noteA
Create a new note. Fails if it already exists. The .md extension is added automatically — do not add .md or other extensions to the path. Never create redirect stubs, backups, or temporary files.
Inputs: path (required), content (required), frontmatter.
delete_noteADestructive
Delete a note. Moves to .trash by default (restore or empty trashed notes from within Obsidian or the filesystem — no tool lists/restores .trash); set permanent=true for an irreversible hard delete.
Inputs: path (required), permanent.
find_broken_linksARead-only
Find wikilinks pointing at notes that don't exist.
Inputs: folder, max_results.
find_orphansARead-only
Find disconnected notes — no inbound links, no outbound links, or both.
Inputs: max_results, include_outlinks_check.
get_backlinksARead-only
Find notes that link to a given note.
Inputs: path (required).
get_daily_noteARead-only
Read today's or a specific date's daily note.
Inputs: date.
get_graph_neighborsARead-only
Walk the link graph outward from a note. Depth 1-5, default 1.
Inputs: path (required), depth, direction.
get_noteARead-only
Read a single note with parsed frontmatter and tags. Path extension is optional.
Inputs: path (required).
get_outlinksARead-only
List all outgoing wikilinks from a note. Shows valid and broken links.
Inputs: path (required).
get_tagsARead-only
List all unique tags in the vault with usage counts.
Inputs: sort_by.
list_canvasesCRead-only
List all .canvas files in the vault.
Inputs: folder.
list_notesB
List and filter vault notes by folder, tags, projects, status, area, or frontmatter.
Inputs: area, tags, limit, folder, +5 more.
move_noteADestructive
Move or rename a note. ALL wikilinks across the vault are updated automatically — do not create redirect stubs at the old path. The .md extension is added automatically. Do not use this to create backups; use delete_note instead (it moves to .trash).
Inputs: new_path (required), old_path (required), update_links.
prepend_to_noteA
Insert text after frontmatter, before the note body. The .md extension is added automatically.
Inputs: path (required), content (required).
read_canvasARead-only
Read canvas structure (nodes + edges).
Inputs: path (required).
remove_canvas_edgesCDestructive
Remove edges from a canvas by ID.
Inputs: edge_ids (required), canvas_path (required).
remove_canvas_nodesADestructive
Remove nodes by ID. Auto-removes dangling edges.
Inputs: node_ids (required), canvas_path (required).
searchBRead-only
Find notes by text, meaning, or exact string.
Inputs: query (required), mode, tags, top_k, +2 more.
update_canvas_edgeCIdempotent
Update properties of an existing canvas edge by ID.
Inputs: edge_id (required), canvas_path (required), color, label, +4 more.
update_canvas_nodeCIdempotent
Update any property of an existing canvas node by ID.
Inputs: node_id (required), canvas_path (required), x, y, +7 more.
update_frontmatterAIdempotent
Merge key-value pairs into YAML frontmatter. Unlisted keys preserved. The .md extension is added automatically.
Inputs: path (required), properties (required).
vault_index_statusARead-only
Check search index health and statistics.
Inputs: no named parameters.
vault_reindexA
Trigger incremental reindex for one note or the entire vault.
Inputs: path.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Most tools target a distinct resource and action, but a few could be confused: search overlaps with list_notes for finding content, and get_graph_neighbors could be mistaken for a combined version of get_backlinks/get_outlinks. Overall, the descriptions are clear enough to separate the graph, note, and canvas operations.
The dominant verb_noun pattern is consistent (create_note, move_note, delete_note, add_canvas_node, etc.), with minor deviations like bare 'search', 'vault_index_status' (noun_status), and singular/plural mismatches in canvas operations (update_canvas_node vs remove_canvas_nodes). These are readable and predictable.
28 tools is on the heavy side for an MCP server, though the breadth is justified by covering notes, daily notes, link analysis, indexing, and canvases. It exceeds the typical well-scoped range and feels dense, but not bloated with near-duplicate functionality.
The note lifecycle is well-covered (create, read, update via append/prepend/frontmatter, move, delete), and link analysis plus canvas CRUD are thorough. Minor gaps exist: there is no in-place body editing or trash restore tool, and daily notes can only be created/read, not modified directly.
Maintenance
Related MCP Connectors
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceA local MCP server that enables AI applications like Claude Desktop to securely access and work with Obsidian vaults, providing capabilities for reading notes, executing templates, and performing semantic searches.830MIT
- AlicenseNot gradedqualityBmaintenanceAn open-source MCP server that makes your Obsidian vault accessible from any AI client with hybrid search, read/write, and graph analysis capabilities.22MIT
- AlicenseNot gradedqualityDmaintenanceA lightweight MCP server that enables AI assistants to securely read, create, and modify notes in an Obsidian vault, with support for semantic search and web scraping.7,721 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables natural language interaction with Obsidian vaults through an MCP server, providing hybrid search, file management, and AI-powered analysis.2-