ObsidianMCP

Read-only MCP server that exposes an Obsidian vault to LLM clients over Streamable HTTP.

Status: v1 feature-complete. All four MCP tools are implemented, all routed through the sharing filter: list_tree (accessible tree, each file annotated with a summary read from its YAML frontmatter summary), read_note (full note content, with a filesystem-level guard against symlink escapes/aliasing), search_notes (case-insensitive full-text search over shared .md notes, ranked snippets), and resolve_links (Obsidian wiki-links and backlinks over the accessible note set only). The operator web panel (/panel) edits which paths are shared.

Settings

All configuration lives in one settings.json — there are no environment variables. Copy the template and edit it:

cp settings.example.json settings.json

{
  "apiToken": "your-mcp-bearer-token",
  "port": 3000,
  "vaultPath": "/abs/path/to/vault",
  "sharingConfigPath": "/abs/path/to/sharing.json",
  "panelPassword": "your-panel-password"
}

vaultPath and sharingConfigPath must be absolute paths (relative values are rejected), so there is no base-directory ambiguity. settings.json holds secrets and is gitignored.

Related MCP server: obsidian-mcp

Run (local)

npm install
npm run build
node dist/index.js               # reads ./settings.json
node dist/index.js /path/to/settings.json   # or an explicit path
# or, without building: npm run dev

• GET /healthz — health check (no auth)

• POST /mcp — MCP endpoint (requires Authorization: Bearer <apiToken>)

• GET /panel — operator panel (only when panelPassword is set; password login)

Run (Docker)

Create settings.json (with in-container paths "vaultPath": "/vault" and "sharingConfigPath": "/config/sharing.json"), then:

VAULT_PATH=/abs/path/to/vault docker compose up --build

VAULT_PATH here is only the Docker bind-mount source for the host vault; the vault is mounted read-only, settings.json read-only, and the sharing config writable so the panel can edit it.

For a remote deployment via Portainer (GHCR image + bind-mounted config over a private network), see deploy/README.md and deploy/portainer-stack.yml.

Sharing config

Which vault paths are exposed is controlled by a JSON file (default ./sharing.json), read fresh on every request. It is a single ordered list of rules:

{
  "rules": [
    { "path": "Projects",           "share": true  },
    { "path": "Projects/secret.md", "share": false }
  ]
}

• path is a vault-relative POSIX path — a folder (shared recursively) or a single file.

• For any path, the longest (most specific) matching rule wins, so a folder can be shared while a descendant is denied, and vice versa.

• Default-deny: a path with no matching rule is not shared. { "rules": [] } shares nothing.

• Dotfiles/dotfolders (e.g. .obsidian) and symbolic links are always excluded, regardless of rules.

The vault is never written to; this file is the only knob.

Operator panel

Set PANEL_PASSWORD and open GET /panel. After a password login it shows the full vault tree with a checkbox per file (folders toggle their descendants). Save rewrites sharing.json as one share: true rule per checked file — so a newly added note stays private until you check it (default-deny). Changes take effect on the next MCP request; no restart. The panel writes only sharing.json, never the vault. In Docker the config is mounted writable while the vault stays read-only; the panel is not mounted unless PANEL_PASSWORD is set.