obsidian-mcp-server

A Go Model Context Protocol (MCP) server for Obsidian vaults. It gives AI agents and development tools direct filesystem access to your vault — no running Obsidian instance required.

Features

• Read, write, and list notes and directories via MCP tools
• Frontmatter — parse and update YAML frontmatter with format-preserving rewrites
• Tags — extract inline #tags, aggregate vault-wide tag counts, add/remove tags
• Backlinks — on-demand reverse link graph (wikilinks and markdown links)
• Mutations — heading-anchored patch, safe delete, and move with confirmation guards
• Full-text search — BM25 Okapi ranked search with match snippets
• Regex/glob search — RE2 regex or filepath glob search across paths and content
• Path security — 4-layer validation: lexical checks, ignore/extension filters, case-insensitive existence lookup, and symlink escape prevention
• Stdio transport — works with any MCP client (Claude Code, Claude Desktop, etc.)
• Streamable HTTP transport (optional) — TLS 1.3 + bearer token auth by default, loopback-only unless explicitly widened; see --transport http in Configuration and SECURITY.md § HTTP transport
• Zero Obsidian dependency — operates on the vault directory directly
• Token counting — responses include approximate token counts (cl100k_base)

MCP Tools

search_notes, search_regex, list_directory, and get_recent_changes results also include an obsidian://open deepLink field per note, built from --vault-name (see Configuration below).

Notes

patch_note semantics: position controls where content is inserted relative to the heading:

• before — inserted immediately before the heading line
• after — inserted after the heading's body (before the next same-level or higher heading)
• replace_body — replaces everything between the heading line and the next same-level heading

search_notes parameters:

Returns: { query, results: [{ path, score, matchCount, matches: [{line, snippet, term}], tokenCount, reason }], total }

search_regex parameters:

Returns: { pattern, scope, results: [{ path, matches: [{line, snippet}] }], total }

Batch tools (read_multiple_notes, get_notes_info): The paths parameter is a JSON array string — e.g. '["Notes/foo.md","Notes/bar.md"]'. summary:true returns headOf (first N runes from headChars, default 200) instead of full content, which is useful for large notes to stay within context limits. Both tools enforce --max-batch (default 10); requests with more paths are silently truncated and the response includes "truncated": true.

Optimistic concurrency (if_match / etag): read_note, read_multiple_notes, and get_notes_info return a SHA-256 etag of the note's content. Pass that value as if_match on write_note, patch_note, update_frontmatter, manage_tags, delete_note, or move_note to make the write conditional — if the note has changed since you read it, the call fails with a REVISION_CONFLICT error instead of silently overwriting someone else's edit. if_match is optional everywhere; omitting it writes unconditionally, as before. Two edge cases: passing if_match for a note that doesn't exist yet is always a conflict (it never creates the note), and move_note's dryRun:true preview does not enforce if_match.

Periodic notes (get_periodic_note, get_recent_periodic_notes): Configuration (folder and date format per granularity) is read from .obsidian/plugins/periodic-notes/data.json inside the vault. If that file is missing, built-in defaults are used: daily notes use YYYY-MM-DD in Daily Notes/, weekly notes use gggg-[W]ww in Weekly Notes/, and so on. offset=0 resolves to the current period, offset=-1 to the previous period (yesterday, last week, etc.), and offset=+1 to the next period. createIfMissing=true creates an empty note at the resolved path if it does not already exist.

get_vault_stats: Returns noteCount, totalBytes, totalLinks, totalTags, topTags (top 20 by count), oldestNote, newestNote, and vaultRoot. Setting includeTokenCounts:true runs token counting across every note — this is expensive for large vaults and is disabled by default.

audit_notes classes:

• orphans — notes that have no tags AND no incoming wikilinks or markdown links (completely isolated notes)
• dangling-links — notes containing links to vault paths that do not exist (broken references)
• untagged — notes with no frontmatter tags and no inline #tags
• duplicate-titles — multiple notes sharing the same filename stem, which causes wikilink ambiguity

Each class result is capped at limit entries (default 20). When results are truncated, the response includes "truncated": true.

MCP Prompts

Prompts are server-defined conversation starters that the host (Claude Code, Claude Desktop) exposes in its UI. Each prompt pulls live vault data and constructs a ready-to-use message for the LLM.

Prompts are invoked from the host's prompt picker (e.g. / in Claude Code). They never modify the vault.

MCP Resources

Resources are read-only vault data that the host can attach directly to a conversation context window — no explicit tool call required.

Static resources (obsidian://vault/*) are always available in the resource picker. Template resources are resolved when the host reads them — if the note does not exist, the resource returns an explanatory empty body instead of an error.

Installation

Install script

Downloads the right binary for your OS/architecture, verifies its checksum, and installs it to ~/.local/bin (override with a second argument):

curl -fsSL https://raw.githubusercontent.com/tylern91/obsidian-mcp-server/main/install.sh | sh

Pin a version instead of latest:

curl -fsSL https://raw.githubusercontent.com/tylern91/obsidian-mcp-server/main/install.sh | sh -s -- v0.2.0

Claude Desktop (.mcpb bundle)

Download obsidian-mcp-<version>.mcpb from the latest release and double-click it — Claude Desktop installs the extension and prompts for your vault path. No manual JSON editing.

Release binary

Download a prebuilt binary from the latest release, verify its checksum, and install:

# macOS (Apple Silicon) — swap the asset name for your platform (darwin-amd64, linux-amd64, linux-arm64)
curl -fLO https://github.com/tylern91/obsidian-mcp-server/releases/latest/download/obsidian-mcp-<version>-darwin-arm64.tar.gz
curl -fLO https://github.com/tylern91/obsidian-mcp-server/releases/latest/download/obsidian-mcp-<version>-darwin-arm64.tar.gz.sha256
shasum -a 256 -c obsidian-mcp-<version>-darwin-arm64.tar.gz.sha256
tar -xf obsidian-mcp-<version>-darwin-arm64.tar.gz
install -m 0755 obsidian-mcp-<version>-darwin-arm64/obsidian-mcp ~/.local/bin/obsidian-mcp

Homebrew (macOS/Linux)

brew tap tylern91/obsidian-mcp
brew install obsidian-mcp

go install

Requires Go 1.27+ to build from source. Building with GOTOOLCHAIN=local on an older Go requires upgrading first — GOTOOLCHAIN=auto (the default since Go 1.21) downloads a matching toolchain automatically.

go install github.com/tylern91/obsidian-mcp-server/cmd/obsidian-mcp@latest

Build from source

Requires Go 1.27+. Building with GOTOOLCHAIN=local on an older Go requires upgrading first — GOTOOLCHAIN=auto (the default since Go 1.21) downloads a matching toolchain automatically.

git clone https://github.com/tylern91/obsidian-mcp-server.git
cd obsidian-mcp-server
make build

Usage

Claude Code

claude mcp add obsidian -s user \
  -e OBSIDIAN_VAULT_PATH="/path/to/your/vault" \
  -- obsidian-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp",
      "args": ["--vault", "/path/to/your/vault"],
      "env": {}
    }
  }
}

Cursor

Edit the vault path after install — the deeplink can't know it in advance.

VS Code

Edit the vault path after install — the deeplink can't know it in advance.

Direct

obsidian-mcp --vault /path/to/your/vault

Print the version and exit:

obsidian-mcp --version

Configuration

Configuration follows CLI flag > environment variable > default precedence.

Examples

# Override extensions to include Excalidraw drawings
obsidian-mcp --vault ./my-vault --extensions ".md,.canvas,.excalidraw"

# Add a custom ignore pattern alongside defaults (you must repeat the defaults
# you want to keep — values fully replace, not merge)
obsidian-mcp --vault ./my-vault \
  --ignore ".obsidian,.git,node_modules,.DS_Store,.trash,Archive,Templates"

# Enable pretty JSON via env var (any ParseBool-compatible truthy value works)
OBSIDIAN_PRETTY=1 obsidian-mcp --vault ./my-vault
OBSIDIAN_PRETTY=true obsidian-mcp --vault ./my-vault

# Verbose logging while debugging an integration
OBSIDIAN_LOG_LEVEL=debug obsidian-mcp --vault ./my-vault

# Streamable HTTP transport instead of stdio (loopback only, TLS + bearer
# token auto-generated on first run — see SECURITY.md § HTTP transport)
obsidian-mcp --vault ./my-vault --transport http --http-port 8443

Precedence in action: with OBSIDIAN_LOG_LEVEL=debug exported, obsidian-mcp --vault ... --log-level info runs at info — the explicit flag wins. Unset flags inherit the env var; if neither is set, the default applies.

Security

All paths are validated through a 4-layer security model before any filesystem operation:

1. Lexical — rejects absolute paths, .. traversal, and null bytes
2. Filter — blocks ignored patterns (.git, .obsidian, etc.) and unapproved extensions
3. Existence — verifies the file exists with a case-insensitive fallback; rejects ambiguous matches
4. Symlink — resolves symlinks and verifies the target remains inside the vault root

The optional --transport http listener has its own security posture (TLS, bearer auth, loopback-only default, session binding) — see SECURITY.md § HTTP transport.

Project Structure

cmd/obsidian-mcp/     Entry point, transport selection (stdio/http)
internal/
  config/             CLI flags, env vars, defaults
  vault/              Path security, CRUD, frontmatter, tags, links, mutations
  tools/              MCP tool registrations and handlers
  response/           Token counting, JSON formatting
  search/             BM25 ranked search, regex/glob
  periodic/           Periodic note resolution (Phase 4)
  prompts/            MCP Prompt templates
  resources/          MCP Resource registrations
  httptransport/      Streamable HTTP transport: TLS, bearer auth, session binding
testdata/vault/       Fixture vault for tests

Development

make build    # compile binary
make test     # go test -race ./...
make vet      # go vet ./...
make fmt      # gofmt + goimports
make run ARGS="--vault /path/to/vault"
make help     # list all targets

License

Apache-2.0