Knap

Knap, for Obsidian. An MCP server over an Obsidian vault. Your notes are plain markdown on disk; this hands them to Claude, ChatGPT or any other MCP client, with the links, tags and frontmatter intact.

Knapping is the craft of striking flakes off obsidian to shape a blade. Knap is also Dutch for clever. Both fit.

Status: works standalone. Nineteen tools over stdio or HTTP against a vault on disk, with 309 tests. The hosted, multi-tenant, phone-first half is being built on top of this package and is not part of it.

What it does

• Read and search notes by text, tag, folder, frontmatter property or date, paginated, so a vault with thousands of notes stays usable.
• Write like a person would. Append to a section, patch one heading, set a frontmatter property. Rewriting a whole note to change two lines is possible and is not the default.
• Keep the graph honest. Backlinks, outgoing links, unresolved links, and a move that rewrites every note pointing at the old path.
• Daily notes resolved from the vault's own settings, so a note lands where your Obsidian would have put it.

Deliberately not included: Dataview and Bases evaluation. Those run inside Obsidian. Searching frontmatter properties covers most of what they get used for, and the server says so at the handshake rather than letting a client write a query it cannot run.

Two writers

Your Obsidian and the AI edit the same files. Every read hands back a revision marker, every body-replacing write requires it back, and a mismatch is a refusal rather than a merge. Writes are atomic, because a half-written note looks exactly like data loss. Delete, move and body-replacing update ask for confirmation; create, append and patch do not.

Open core

This is the public package: one vault, from environment variables, over stdio or HTTP. A private package adds the hosted, multi-tenant service on top of it, and extends this one through documented seams only. It never forks this code, and nothing here depends on it.

Same split as odoo-mcp-pro and squirrel-mcp.

Try it

make install
make check VAULT=~/vaults/your-vault    # opens the vault, reports what is in it

Then point a client at it. For Claude Desktop or Claude Code:

{
  "mcpServers": {
    "knap": {
      "command": "/path/to/knap-mcp/.venv/bin/python",
      "args": ["-m", "knap_mcp", "--vault", "/path/to/your/vault"]
    }
  }
}

Ask it "which tags are in my vault" to confirm.

Development

make lint     # ruff + ty + the line budget
make test     # 309 tests: fake provider, plus a real seeded vault in a tmpdir
make smoke    # a real MCP client driving the server as a subprocess
make test-all

Read CLAUDE.md for the architecture and conventions.

By Pantalytics.