Headless Obsidian MCP

An MCP server that gives AI assistants full access to an Obsidian vault — search, the link graph, tags, and structure-aware editing — without needing a running copy of Obsidian. Ideal for a headless server running your Hermes or OpenClaw agents.

It reduces token cost and removes the need for your agent to understand Obsidian vault conventions, so your agent can read your vault as a knowledge base rather than a folder of text files: [[wikilinks]] resolve the way Obsidian resolves them, tags unify inline #tags with frontmatter, and edits are surgical (change one section or one tag without rewriting the note).

Read-only by default. Out of the box the server exposes only read tools; writing is opt-in through a single environment variable.

Status: 0.x. The server is tested and in daily use, but the tool surface is still settling — tool names, parameters, and return shapes may change between releases. Following semver's 0.x convention, breaking changes bump the minor version (0.2.0) and fixes bump the patch (0.1.1). Pin a version if you depend on a specific tool contract.

What it can do

Templates from Obsidian's core Templates plugin are supported ({{title}}, {{date:FORMAT}}, …); Templater scripting is not.

→ Full tool reference — all 49 tools with parameters and return shapes.

Related MCP server: Obsidian MCP Tool Server

Quick start

Requires Node.js 20+, ripgrep, and an Obsidian vault.

git clone <this-repo> && cd headless-obsidian-mcp
npm install && npm run build
export OBSIDIAN_VAULT_PATH="/path/to/your/vault"
npm start

Then point an MCP client at it. For Claude Desktop (~/.config/claude/claude_desktop_config.json on macOS/Linux, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/headless-obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/vault"
      }
    }
  }
}

Restart the client and the server appears as obsidian. To let the agent edit the vault, add "OBSIDIAN_TOOLS": "all" to that env block — see Enabling writes.

Ready-to-copy configs for Claude Desktop, Claude Code, and Docker are in examples/.

Configuration

Only OBSIDIAN_VAULT_PATH is required. .env.example documents all eight variables the server reads.

Nothing here loads a .env file — an MCP server inherits its environment from the client that spawns it. Set variables in your client's env block (or pass --env-file to Docker).

Enabling writes

OBSIDIAN_TOOLS selects exactly which tools the server exposes. Unset, it means reads: the 24 write tools are hidden from the tool list, and calling one is rejected.

OBSIDIAN_TOOLS="all"                              # everything
OBSIDIAN_TOOLS="reads,tasks.write,sections.write" # read all; write only tasks and sections
OBSIDIAN_TOOLS="all,-bulk,-delete_note"           # everything except the destructive ones
OBSIDIAN_TOOLS="-templates,-tasks"                # reads, minus two groups
OBSIDIAN_TOOLS="search,notes.read"                # minimal search-and-read agent

Selectors are case-insensitive and applied left to right — a plain token adds, a - prefix subtracts. Valid tokens are the meta-groups all / reads / writes, a domain group, a mode slice like notes.write, or an individual tool name. Evaluation starts from nothing, unless the first token subtracts, in which case it starts from reads — so -templates trims the read surface and can never accidentally expose writes.

The eleven domain groups:

get_config sits in no group and is always exposed — its tools section reports the active policy, so an agent can discover why a tool is missing.

Excluding tools also saves tokens: an excluded tool is a schema the client never carries in context.

An unknown selector, or a policy that selects nothing, aborts startup with the valid vocabulary listed. The policy gates the MCP server only; the query CLI is the operator's own tool and ignores it.

Git safety net (OBSIDIAN_GIT_SYNC)

If your vault is a git repository, the server can snapshot every write:

OBSIDIAN_GIT_SYNC_INTERVAL sets the timer cadence in seconds (default 300); OBSIDIAN_GIT_REMOTE names the remote (default origin).

The guard is fail-closed: in any mode but off, a write is refused before touching disk if the vault isn't a usable git repo, and a failed post-write commit throws — a write never lands without its snapshot. The lone exception is the background timer tick, whose failures are recorded in get_config's sync.last_error rather than thrown, since no write is in flight to fail.

Conflicts are never blocking or destructive. On a real merge conflict, per file: if both sides changed the note, your version is preserved as a <note> (conflicted YYYY-MM-DD HHMMSS) copy and the canonical path takes the remote's; if the remote deleted a note you'd modified, the same copy preserves your version; if you deleted a note the remote modified, the remote version is restored. Find unreconciled copies with list_vault_issues kind:"conflicts".

Docker

The Dockerfile builds a multi-stage node:20-alpine image with ripgrep and git installed — both are hard runtime dependencies, not conveniences.

docker build -t headless-obsidian-mcp .
docker run -i --rm -v "$HOME/vault:/vault:ro" headless-obsidian-mcp

-i is load-bearing: this is a stdio server, and without an open stdin the transport never comes up. The vault mounts at /vault and the container runs as the unprivileged node user. For writes, drop :ro and add --user "$(id -u):$(id -g)" so new files land owned by you. Client config: examples/mcp.docker.json.

There's no docker-compose.yml by design — an MCP stdio server is spawned per client, not supervised as a service.

Development

npm run dev     # watch mode via tsx, no build step
npm run build   # compile to dist/
npm test        # node:test via tsx
npm run query   # query CLI — see docs/CLI.md

mise run <task> works for each if you use mise.

The query CLI calls the tools directly and prints raw JSON, which makes it the fastest way to try something without wiring up a client.

Tests build a throwaway fixture vault in a temp directory and cover link resolution, tag aggregation, listing and recency, index cache invalidation, and the security guards (path traversal, symlink escapes, frontmatter hardening). CI runs build and tests on Node 20 and 22 for every PR and push to main, installing real ripgrep and a git identity — the suite drives the actual rg binary and real repositories rather than stubs.

Design rationale, tool-naming taxonomy, and the invariants that keep the tool surface coherent live in CLAUDE.md.

Agent skill

skills/obsidian-vault/SKILL.md is a copyable Agent Skill — drop it in ~/.claude/skills/obsidian-vault/ to give an agent workflow guidance for this server: which tool answers which intent, anti-patterns worth avoiding, and multi-step recipes for fixing broken links, processing the daily note, and restructuring without breaking the graph.

Acknowledgments

This project began as a Node.js port of notes-mcp by Boaz Yaniv, and has since been substantially extended with knowledge-base, structure-aware editing, and vault-management tools. The original is MIT licensed; that license and copyright are retained in LICENSE.

Thanks also to mcpvault by bitbonsai, whose Obsidian MCP server was a useful reference while shaping this project's tool surface.

License

Released under the MIT License.