notes-vault-mcp

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, stems every word in the vault's languages so äppelpressar finds äppelpressen and pressing finds presses, 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.

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:

• .vault/schema.yml — the frontmatter contract, copied from the built-in default so you can edit it.
• Areas.base, Open tasks.base, Resources.base, Backlog.base, Log.base — Obsidian Bases views over the same structure.

It then prints a CLAUDE.md snippet to stdout: the workflow rules an agent needs on its side of the conversation.

The schema

.vault/schema.yml is deep-merged over the built-in default, so it only needs to carry what differs. The default lays out five folders:

and the contract for a note:

frontmatter:
  required: [title, date, updated, tags, status]
  optional: [kind, area, summary, path, superseded_by]
  area_required_in: [Projects, Resources, Log]
  status_values: [draft, active, complete, superseded]
  kind_values: [system, task, trap, howto, decision, reference, log]

Each kind carries a one-line rule saying when a note is that kind, and the server puts the rules in its instructions so every client picks kinds the same way:

kinds:
  trap: "a gotcha that bit once and will bite again; nothing to do, nothing was chosen"
  decision: "a choice and its reasons; something was chosen, alternatives were dropped"
  howto: "steps that are known to work; nothing chosen, nothing open"

A vault adds a kind by adding an entry (research: "reading notes on a topic; no task, no decision"), rewrites a rule by restating it, and drops a kind by setting it to null. kind_values alone, without rules, still works.

path is what ties a note to code: a comma-separated list of directories (~ is kept as written and also indexed expanded). That is what context and the session hook match against.

The repo log is one note per repo, and both its filename and its line format are schema settings:

log:
  folder: Log
  file_format: "{repo}-log.md"
  entry_format: "- [{date}] {line} | commits: {commits} | {area}"

file_format takes a single {repo} placeholder, and the default suffix is what keeps the log clear of the hub note: with Areas/myapp.md and Log/myapp.md both in the vault, Obsidian cannot resolve [[myapp]]. Every place that builds the log path reads this setting — log_append, the log tail in context, the stop hook's unlogged-commit check, changelog and lint — so changing it moves all of them at once. Rename the existing files to match when you change it.

language is the vault's primary language and other_languages the rest, as ISO codes (language: sv, other_languages: [en]); search stems in every one Snowball supports, and changing them rebuilds the index. When nothing matches, the reply tells the client which languages the vault is written in so it can translate the terms and search again; a partial result says the same in one line. A stemmed-only match weighs stemmed_weight (0.5 by default, below the body's 1.0), so the exact form ranks first.

Also configurable: the tag vocabulary and whether it is enforced, the synonym groups search expands, stale_after_days, and the search weights.

Tools

Every call refreshes the index first, throttled to at most once every 20 seconds.

search filters: folder, status, tag, kind, area, path_prefix, since, include_archive, include_superseded, limit.

What lint reports

broken_frontmatter, missing_required (per field), missing_area, unknown_tags (only when the vocabulary is strict), unresolved_links, orphans (no inbound wikilink; log and archive ignored), stale_active, archive_status_mismatch, duplicate_stems, superseded_target_missing. With --park-stale the open task notes untouched for longer than stale_after_days are set to backlog (priority low, source veckolint <date>) before the report and listed under parked, so active always means touched within the window; reviving one is set_status(path, "active").

uvx notes-vault-mcp lint
uvx notes-vault-mcp lint --write "Log/lint-$(date +%F).md"
uvx notes-vault-mcp lint --write Log/lint.md --park-stale

Hooks

Two Claude Code hooks, both reading the hook JSON on stdin and both exiting 0 whatever happens.

session-start prints the context bundle for the working directory, then — for each system note it returned — the commits touching that note's path since the note was last updated. That is the answer to "is this note still true?" before the agent believes it.

stop blocks the end of a session that left work unrecorded: commits from the last 24 hours whose sha does not appear in the repo log, and open task notes older than the schema's stale_after_days that the session read or wrote (found through the vault tool calls in the session transcript). It returns {"decision": "block", "reason": ...}, or nothing at all when the vault is up to date. Stale notes the session did not touch are the next session's business: context lists them under triage with the three ways to settle each (close, a dated line, or park in the backlog), not at every stop. Set VAULT_STOP_HOOK=off to silence the hook.

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "uvx notes-vault-mcp hook session-start" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "uvx notes-vault-mcp hook stop" }] }
    ]
  }
}

Other commands

notes-vault-mcp serve --transport stdio          # the default
notes-vault-mcp sync --rebuild                   # drop the index and read every note again
notes-vault-mcp search "bokning" --limit 5       # the same ranking, from a shell
notes-vault-mcp changelog myapp 2026-08 --repo-path ~/projects/myapp
notes-vault-mcp changelog myapp 2026-08 --repo-path ~/projects/myapp --write
notes-vault-mcp changelog --all                  # this month (and last month during its first week)

changelog prints the log lines, the git commits grouped by day, and the repo's notes dated inside the period. With --write it keeps that as a period page, Log/<repo>-<period>.md, between the markers <!-- changelog:generated --> and <!-- /changelog:generated -->; prose above the markers (a summary written by an agent at month end) is left alone, and the page's status follows the calendar. --all does it for every repo the session-start hook has seen on this machine, and the stop hook runs that once a day, so the pages stay current without a cron.

Backlog

notes-vault-mcp backlog --area myapp --priority high

A backlog item is a task note with status: backlog, an area, a one-line summary, an optional priority (urgent, high, medium, low) and an optional source (who said it and when, or a sha). backlog_add files one from a conversation the moment something is deferred; backlog lists them by priority then age, filtered by area or family; context shows the ones relevant to the current repo apart from the open tasks. Picking an item up is setting its status to active; finishing it is close. Lint leaves backlog notes alone however old they get, and flags a complete note that was never closed. init writes Backlog.base next to the other Obsidian bases.

HTTP transport

VAULT_TOKEN=$(openssl rand -hex 32) notes-vault-mcp serve --transport http --host 0.0.0.0 --port 8765

Streamable HTTP on /mcp, with four ways to authenticate: --auth bearer (the default), --auth oidc, --auth builtin and --auth forwarded.

bearer is the LAN mode. Every request must carry Authorization: Bearer $VAULT_TOKEN; anything else gets 401 before it reaches the server. VAULT_TOKEN is mandatory in this mode — the command refuses to start without it. It is a single token with full access, and claude.ai cannot use it.

The Host header follows what the server listens on. Bound to localhost, only localhost, 127.0.0.1 and [::1] are answered, anything else gets 421; bound to another address, every Host is answered. To keep the check on while serving a name of your own, a Kubernetes Service or a LAN hostname, list it in VAULT_ALLOWED_HOSTS or set VAULT_PUBLIC_URL: then that name and localhost are answered and the rest get 421.

oidc and builtin speak OAuth, which is what a Claude connector needs. See Remote: claude.ai, Claude Desktop and mobile.

forwarded is for a server that sits behind a proxy which already did the OAuth: it trusts a signed identity header and serves one vault per subject. See Behind a proxy: one vault per person.

Remote: claude.ai, Claude Desktop and mobile

Run the server over HTTPS with --auth builtin or --auth oidc and claude.ai can add it as a custom connector. Connect it once on the web and the same connector appears in Claude Desktop and in the mobile app.

One server instance serves one vault.

Prerequisites

• A vault: an S3-compatible bucket with a key scoped to it, or a folder on the host.
• Docker, or uv on the host.
• A domain pointing at the machine, with TLS in front of the server. The examples under deploy/ put Caddy there, which fetches the certificate itself.
• For --auth oidc: an OpenID Connect provider you already run.

The two modes

Environment

The MCP endpoint is VAULT_PUBLIC_URL + /mcp. That is the URL you paste into claude.ai.

Scopes

• vault:read — search, read_file, list_files, context, lint, backlog.
• vault:write — write_file, append_file, move_file, delete_file, close, log_append, backlog_add.

A write tool called with a read-only token fails with an error saying the token may only read the vault, rather than half-writing or silently doing nothing.

Built-in login, from zero

cd deploy/caddy-builtin
cp .env.example .env
$EDITOR .env
docker compose up -d
docker compose exec vault notes-vault-mcp owner set-password

Then, in claude.ai: Settings → Connectors → Add custom connector → the /mcp URL, e.g. https://vault.example.com/mcp. Nothing else is needed: the server registers the client itself. The browser lands on the server's login page, which asks for the owner password and shows two checkboxes, read and write. Clear write to hand out a read-only connector.

What has been connected, and how to disconnect it:

docker compose exec vault notes-vault-mcp tokens list
docker compose exec vault notes-vault-mcp tokens revoke <client_id>

The password hash and the tokens live in auth.sqlite in the vault-data volume. Back that volume up; losing it means every client has to connect again.

OIDC, from zero

cd deploy/caddy-oidc
cp .env.example .env
$EDITOR .env
docker compose up -d

The server is a resource server here: it validates the provider's access tokens and never sees a password. A user in the write group gets vault:read and vault:write, a user in the read group only vault:read, and anyone in neither is refused.

Add the connector in claude.ai the same way. With a provider that supports dynamic client registration you are done. With one that does not (Pocket ID, Authentik), register the client in the provider first and paste its client id and secret under the connector's Advanced settings; the redirect URI to allow in the provider is the one claude.ai shows in that dialog.

Pocket ID

claude.ai sends the MCP resource (the /mcp URL) as an OAuth resource parameter, and Pocket ID only accepts a resource it knows as an API. So:

1. Settings → APIs → Add API: a name and the resource identifier, exactly VAULT_PUBLIC_URL + /mcp. Add two permissions: key vault:read and key vault:write, with the names your family will see on the consent screen.
2. Settings → User Groups: create vault (read) and vault-writers (write) and put users in them.
3. Settings → OIDC Clients → Add: name claude.ai, callback URL https://claude.ai/api/mcp/auth_callback, PKCE on, public client off, allowed user groups vault. Under API access, grant the API with both permissions (user-delegated). Copy the client id and secret.
4. On the server: VAULT_OIDC_ISSUER is Pocket ID's base URL, VAULT_OIDC_AUDIENCE is the resource identifier from step 1 (Pocket ID puts it in aud), and VAULT_OIDC_SCOPES is openid profile email groups vault:read vault:write.
5. In claude.ai, add the connector with the client id and secret under Advanced settings.

The user's groups decide what a token may do; the client's permissions only matter when the provider reports no groups at all, in the token or through userinfo.

Kubernetes

deploy/k8s/ holds plain manifests: a Deployment with a PVC mounted at /data, a Service, an Ingress and an example Secret.

cp deploy/k8s/secret.example.yaml secret.yaml
$EDITOR secret.yaml
$EDITOR deploy/k8s/ingress.yaml
kubectl apply -f secret.yaml -f deploy/k8s/deployment.yaml -f deploy/k8s/service.yaml -f deploy/k8s/ingress.yaml

The Deployment runs --auth builtin; for OIDC change the --auth argument and fill the VAULT_OIDC_* keys in the Secret. The readiness probe hits /.well-known/oauth-protected-resource/mcp, the one route that answers without a token in both modes; when VAULT_PUBLIC_URL carries a path, that path sits in the probe URL too. Set the owner password once the pod is up:

kubectl exec -it deploy/notes-vault-mcp -- notes-vault-mcp owner set-password

Fill in ingressClassName and point secretName at a TLS certificate — an existing secret, or one cert-manager issues.

Behind a proxy: one vault per person

--auth forwarded is for an organisation that already runs an OAuth authorization server in front of its MCP servers and forwards the caller's identity as a signed token in a header (the pattern Cloudflare Access uses with Cf-Access-Jwt-Assertion). The server verifies that token with the proxy's public key, takes the subject from it, and serves that subject's own vault: a prefix per person in one bucket (or a folder per person under VAULT_PATH), with its own index, its own .vault/schema.yml and a welcome note, all created on the first request. Nothing is provisioned by hand; granting access at the proxy is the whole onboarding.

notes-vault-mcp serve --transport http --host 0.0.0.0 --port 8765 --auth forwarded

The contract with the proxy: a request without a valid identity gets 403 with no WWW-Authenticate challenge (advertising an authorization server here would point clients past the proxy), the transport is stateless with plain JSON responses so a buffering proxy needs no Mcp-Session-Id, the Host header is not checked, and /up answers ok without a token for readiness probes. The OAuth metadata routes are not served in this mode; the proxy owns them.

The token needs iss, aud, sub and exp; email and name are used when present. Subjects that are not plain identifiers are hashed before they name a folder.

Obsidian through the same server

Each vault is also served over WebDAV at VAULT_PUBLIC_URL/dav/, for Obsidian's Remotely Save plugin, which cannot do OAuth. The person asks Claude to run obsidian_access; the server mints a personal token, returns it once and stores only its hash. Remotely Save gets the /dav/ address, any username (the email is the convention) and that token as the password. Running obsidian_access again rotates the token. The proxy must pass /dav/* straight through, with the client's Authorization header and the WebDAV verbs and headers (PROPFIND, MKCOL, MOVE, COPY, Depth, Destination, Overwrite) intact. The welcome note written on the first request carries these instructions for the person.

Development

uv sync
uv run pytest
uv run ruff check .

The test suite runs against a fixture vault under tests/fixtures/vault/ and a moto-mocked S3 bucket. It never touches a real bucket.

License

MIT. See LICENSE.