Notes Vault Mcp · LLM Mart

Name: Notes Vault Mcp
Author: LLM Mart

No install snippet on purpose. A working MCP config is a command, its arguments and an environment block — the last two are where API keys live, so this catalogue never stores them and cannot publish them. Follow the link above for the authors' own instructions.

An MCP server for a vault of markdown notes — the kind Obsidian keeps: a folder of .md files with YAML frontmatter. The vault lives either in a local directory or in an S3 bucket (MinIO included), and the server gives an agent a cheap, indexed way to read and write it.

The point is that an agent should be able to answer "what do we already know about this?" in one call, and should be told when the vault has drifted away from the code. So the server does more than read and write files:

A local SQLite index. Every tool call refreshes it, fetching only the notes whose version changed. Search never downloads the vault.
Full-text search with BM25 ranking, folder weights, recency decay and a status factor, so the living system note outranks a two-year-old archived plan on the same words.
A schema. The frontmatter contract lives in the vault as .vault/schema.yml: which folders exist and what each is for, which fields are required, which statuses and kinds are legal, which folders must link an area. Writes are validated against it and refused when they do not hold.
A lifecycle. close archives a finished note and stamps its status; log_append writes one dated line per repo per session; lint reports every kind of drift it can see.
Session hooks for Claude Code: session-start hands the agent the system notes for the repo it is about to touch — plus the commits made since each note was last updated — and stop refuses to end a session that left commits unlogged or notes stale.

Swedish or English notes both work: the index folds diacritics, and the schema carries a synonym list so bokning finds booking.

Install

As a Claude Code plugin

claude plugin marketplace add https://github.com/gronare/claude-plugins
claude plugin install vault@gronare

The plugin asks for the vault settings and passes them as CLAUDE_PLUGIN_OPTION_* environment variables, which this server reads as if they were the bare names.

As an MCP server, straight from PyPI

claude mcp add vault -s user \
  -e VAULT_PATH=$HOME/vault \
  -- uvx notes-vault-mcp

Or against S3 / MinIO:

claude mcp add vault -s user \
  -e S3_ENDPOINT=https://minio.example.com \
  -e S3_ACCESS_KEY=... \
  -e S3_SECRET_KEY=... \
  -e S3_BUCKET=vault \
  -- uvx notes-vault-mcp

As a container

claude mcp add vault -s user -- \
  docker run --rm -i \
  -e S3_ENDPOINT -e S3_ACCESS_KEY -e S3_SECRET_KEY -e S3_BUCKET \
  ghcr.io/gronare/notes-vault-mcp:latest

Configuration

Every variable is also read from CLAUDE_PLUGIN_OPTION_<NAME>, which is how the Claude Code plugin passes its user config. The bare name wins when both are set.

Variable	Required	Meaning
`VAULT_PATH`	for a local vault	Directory holding the vault. Selects the local backend.
`S3_ENDPOINT`	for an S3 vault	Endpoint URL, e.g. `https://minio.example.com`.
`S3_ACCESS_KEY`	for an S3 vault	Access key.
`S3_SECRET_KEY`	for an S3 vault	Secret key.
`S3_BUCKET`	for an S3 vault	Bucket holding the vault.
`S3_PREFIX`	no	Key prefix inside the bucket.
`S3_REGION`	no	Region, default `us-east-1`.
`VAULT_CACHE_DIR`	no	Where the index lives, default `~/.cache/notes-vault-mcp`.
`VAULT_SCHEMA`	no	Local path to a schema file, overriding the one in the vault.
`VAULT_TOKEN`	for `--auth bearer`	Static bearer token for the LAN mode of `--transport http`.
`VAULT_STOP_HOOK`	no	`off` disables the stop hook.

Set VAULT_PATH or the four S3_* variables. With neither, the server exits with one line saying so.

First run

uvx notes-vault-mcp init

init writes into the vault, and refuses to overwrite anything without --force: