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, mtime-based 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)

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 serve

First run does a full index of the vault - takes a few minutes depending on size. Subsequent starts run incremental index only.

CLI flags

some-vault-some-mcp serve [--transport sse|stdio] [--host 0.0.0.0] [--port 3789]

CLI flags override env vars.

Environment variables

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-mcp

Runs 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.

Read

get_note

Read a single note with parsed frontmatter and tags.

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.

Write

create_note

Create a new note. Fails if it already exists.

append_to_note

Append text to the end of an existing note.

prepend_to_note

Insert text after frontmatter, before the note body.

update_frontmatter

Merge key-value pairs into YAML frontmatter. Unlisted keys preserved.

move_note

Move or rename a note. Rewrites wikilinks vault-wide by default.

delete_note

Delete a note. Moves to .trash by default; use permanent for hard delete.

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.

create_daily_note

Create a daily note for today or a given date. Fails if one exists. Supports {{date}} placeholder in templates.

Tags

get_tags

List all unique tags in the vault with per-note usage counts.

Link graph

get_backlinks

Find notes that link to a given note.

get_outlinks

List all outgoing wikilinks from a note. Shows valid, broken, and embed links separately.

find_orphans

Find disconnected notes - no inbound links, no outbound links, or both.

find_broken_links

Find wikilinks pointing at notes that don't exist.

get_graph_neighbors

Walk the link graph outward from a note via BFS.

Canvas

list_canvases

List all .canvas files in the vault.

read_canvas

Read canvas structure (nodes + edges).

create_canvas

Create a new .canvas file with optional initial nodes/edges. Fails if it already exists.

add_canvas_node

Add a node (text/file/link/group) to a canvas. Position auto-computed via grid layout if omitted.

update_canvas_node

Update any property of an existing canvas node by ID. Only provided fields are changed.

remove_canvas_nodes

Remove nodes by ID. Auto-removes dangling edges.

add_canvas_edge

Add an edge between two canvas nodes with full property support.

update_canvas_edge

Update properties of an existing canvas edge by ID. Only provided fields are changed.

remove_canvas_edges

Remove edges from a canvas by ID.

Index management

vault_index_status

Check search index health and statistics. No arguments.

vault_reindex

Trigger incremental reindex for one note or the entire vault.

MCP resources

• obsidian://note/{path} - read a note by path

• obsidian://tags - all tags

• obsidian://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_orphans

Overrides 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:

1. Exact relative-path match (case-insensitive)

2. Path-suffix match (if link contains /)

3. Basename match with proximity tie-break (deepest shared path prefix with source)

4. Alias match (frontmatter aliases)

First matching step wins.

Security boundaries

• All paths validated against vault root - rejects ../, null bytes, symlink escapes

• .obsidian, .git, .trash excluded from indexing and tool access

• Optional Bearer token auth on SSE transport

• Docker container runs as non-root

• Bounded frontmatter parsing prevents YAML bombs

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 provider

Running from source

VAULT_PATH=/path/to/vault uv run some-vault-some-mcp serve

To 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                      # everything

Test fixtures live in tests/fixtures/vault/.

Releasing

See RELEASING.md.