Grove

Open-source MCP server that makes your Obsidian vault searchable and writable from any AI client.

Six tools, one git-backed vault, single-user. Claude, ChatGPT, Cursor, or any MCP-compatible client connects and gets structured access — search, read, write-back, graph diagnostics. Your vault stays yours: markdown files in a git repo, versioned forever.

┌─────────────────────────────────────────────────────────┐
│              MCP client (Claude / Cursor / …)            │
└──────────────────────┬──────────────────────────────────┘
                       │ MCP — Streamable HTTP + Bearer
                       ▼
┌─────────────────────────────────────────────────────────┐
│                       grove-server                       │
│   6 tools · write queue · provenance · discovery        │
└──────────────────────┬──────────────────────────────────┘
                       │
            ┌──────────┼──────────┐
            ▼          ▼          ▼
        Hybrid      Vault       Discovery
        Search      (git)        worker
      BM25+Vec               (extract → link)

About this repo. Grove was a hosted product 2026-04 → 2026-05. The repo
you're looking at is the open-source cathedral that came out of it: a
personal MCP layer over an Obsidian vault, single-user, self-host. The
multi-tenant SaaS layer, autonomous-agent layer, encryption, trails,
waitlist, and admin portal have all been stripped. See RETROSPECTIVE.md
for the full history.

The six tools

Every write is a git commit. Every commit can carry provenance trailers that the read path surfaces via blame so future readers know what's the user's standing thinking vs an AI's moment-in-time synthesis.

Quick start

You need:

• Node ≥ 22
• A git-backed Obsidian-style markdown vault on disk
• A QMD index for the vault (Grove reads BM25 + vector hits from it)
• A Voyage AI API key for per-write embeddings (voyage-4-large)

git clone https://github.com/jmilinovich/grove.git
cd grove
npm install

Set the env vars:

export GROVE_VAULT=/path/to/your/vault       # absolute path to the git repo
export GROVE_API_KEY=$(openssl rand -hex 32) # your bearer token — keep secret
export VOYAGE_API_KEY=...                    # Voyage AI key for embeddings

Then start the server:

npx tsx src/server.ts

It listens on http://127.0.0.1:8420/mcp. Point any MCP client at that URL with Authorization: Bearer <GROVE_API_KEY>.

Local-only without a token

For purely local development you can disable auth:

GROVE_AUTH=none GROVE_VAULT=/path/to/vault npx tsx src/server.ts

Only do this when the listener is bound to localhost.

Discovery worker (optional)

The discovery worker runs in the background and auto-wikilinks new notes by extracting entities from each write. It's a separate process:

GROVE_VAULT=/path/to/vault \
ANTHROPIC_API_KEY=... \
npx tsx src/discovery-worker.ts

If you don't run it, writes still work — they just don't get auto-linked. The discovery queue + cache live in ~/.grove/state.db and will resume when the worker comes back.

Env reference

What's in the box

src/
├── server.ts          # MCP HTTP server, the 6 tools, bearer-auth gate
├── rest.ts            # write / delete / move / batch handlers (git write-queue)
├── write-queue.ts     # single-writer mutex per vault
├── hybrid-search.ts   # BM25 + vector + RRF fusion over the QMD index
├── embed-single.ts    # per-write embed → Voyage AI → QMD index
├── notes-validate.ts  # frontmatter validation, hash, serialize/parse
├── provenance.ts      # durable/perishable voice, commit trailers
├── blame.ts           # per-segment authorship from git blame + trailers
├── discovery*.ts      # extract → link engine (auto-wikilinking on write)
├── graph-health.ts    # vault health metrics + flags
├── vault-graph.ts     # wikilink graph + clusters
├── vault-stats.ts     # cached stats for vault_status
├── vault-config.ts    # detection + loading of the vault structure
└── db.ts              # single SQLite state-db for discovery + provenance + blame

Code conventions

• TypeScript strict mode. No any except at untyped externals.
• Raw node:http. No Express / Fastify.
• Node ≥ 22, ESM only, built-in fetch + crypto.
• Dependencies are intentionally minimal (@modelcontextprotocol/sdk, better-sqlite3, zod, yaml).
• The vault is sacred — Grove is plumbing. Never restructure or make policy decisions about vault content.

Architecture rules

1. The vault is the source of truth. All other state (state.db, QMD index) is derived. If they diverge, the derived state is wrong — rebuild it.
2. All writes are serialized via the write queue. No concurrent git operations.
3. Every write creates a git commit with attribution.
4. Search index updates synchronously on write so the agent's next call sees the change.
5. Keep the tool count small. Six tools today. If you're adding a tenth, stop and reconsider.

License

MIT. See LICENSE.