Skip to content

Obsidian Skill

Routes file operations to MCPVault, app actions to Obsidian CLI, and sync tasks to Git.

Install with one command via skills.sh
npx skills add bitbonsai/mcpvault

Search notes

Full-text search matches filenames and content, then ranks results with BM25.

Manage tags and frontmatter

Add or remove tags, and update frontmatter fields without rewriting note content.

Edit notes through MCPVault

Read, write, and patch tools validate paths against the configured vault root.

Run Git sync

Optional Git commands commit, pull, and push a vault after checking repository setup.

Routing Matrix

Each operation maps to exactly one backend. The skill picks the right one automatically.

OperationMCPObsidian CLIGitNotes
Read note✓——Vault-scoped read via MCP
Write / patch note✓——Validated writes through MCPVault
Search vault✓——BM25-ranked full-text search
Resolve [[wiki links]]✓——wiki_link picks the shallowest match first, then locale-sorts equal-depth paths; other matches are returned as alternatives
Manage tags / frontmatter✓——Frontmatter merge through MCP
Move / rename notes✓——MCP move followed by explicit backlink search, repair, and verification
Open note in Obsidian—✓—Requires the desktop app running
Trigger plugin commands—✓—Workspace actions, plugin APIs
Export to PDF—✓—App-level rendering pipeline
Sync vault across devices——✓Git commit, pull, and push
Automated backup——✓Cron / launchd, no UI needed

Flow Cheat Sheet

The requested operation determines whether the skill uses MCPVault, Obsidian CLI, or Git.

Intent Routing

1.If the user asks to read/write/search notes, route to MCP tools.
2.If they ask to open or trigger app-level behavior, route to Obsidian context.
3.If they ask to sync/backup/store with git, route to Git CLI.

Git Sync Flow

1.Preflight: verify git, repo, identity, and remote
2.Ask one targeted question if setup is incomplete
3.Run: git add -A → git commit (if changes) → git pull --rebase → git push
4.Stop on conflicts and provide manual next steps

Expanded Flow Playbook

Open for routing rules, preflight logic, and an end-to-end example

Routing defaults

  • -MCP first for read/write/search/frontmatter/tags and all note moves.
  • -Obsidian context for app/editor/plugin-specific behavior and read-only backlink discovery.
  • -Git CLI for sync, backup, and versioning actions.

Safe note rename flow

  1. Search for the old wikilink target by vault-relative path and filename stem.
  2. Move the note with MCP move_note, even when Obsidian is running.
  3. Patch exact wikilink targets while preserving aliases, embeds, and heading or block fragments.
  4. Search again and report stale references. Do not claim exhaustive repair if the 20-result cap is reached or the basename is ambiguous.

The skill does not invoke obsidian move automatically. Delayed stale-offset rewrites can corrupt notes edited while the command is still running (#176).

Preflight checks before sync

git --version
git rev-parse --is-inside-work-tree
git config user.name
git config user.email
git remote -v

If any check fails, ask one targeted setup question with a recommended default.

Example conversation

User:Use git to store my vault and keep it synced.
Skill:I will run a git preflight first (git, repo, identity, remote), then set up anything missing with one targeted question.
Skill:Preflight OK. Running sync: git add -A → git commit (if changes) → git pull --rebase → git push.
Skill:Done. Vault synced to origin/main. No force push used.

What It Is

MCP Server

Handles note reads, writes, searches, patches, and moves. It validates inputs and rejects paths outside the configured vault.

Obsidian CLI

Uses Obsidian's official CLI for operations that need the running desktop app: active file, opening notes in the editor, daily notes with template expansion, read-only backlink discovery, and plugin commands. A preflight checks the installed CLI at runtime instead of assuming a fixed version.

Git Sync

Git commits, pulls, and pushes vault files. Cron, launchd, or CI can run the commands without Obsidian.

Git-Based Vault Sync

Repository setup, automation, and conflict notes

How it works

An Obsidian vault is a folder of markdown files. Run git init inside it, add a remote, then commit, pull, and push like any repository.

Headless automation

# cron job or launchd plist
cd /path/to/vault
git add -A
git commit -m "backup $(date +%Y-%m-%d)"
git push

No Obsidian CLI required. Works on servers, NAS, or any headless machine.

Optional: Obsidian Git plugin

The Obsidian Git community plugin (8k+ stars) adds GUI-driven auto-sync from within the app: auto-commit on interval, pull on startup, push on close, and a source control sidebar.

Caveats

  • -Commit intervals: Git sync runs when changes are committed.
  • -Merge conflicts: Editing the same note on two devices before syncing requires manual resolution.
  • -Large binaries: Images and PDFs may need .gitignore or Git LFS.
  • -Workspace files: Add .obsidian/workspace.json to .gitignore.

Recommended .gitignore

.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/plugins/obsidian-git/data.json
.trash/

When To Use

Trigger phrases

>search my vault for...MCP
>update the frontmatter on...MCP
>tag all notes about...MCP
>open this note in ObsidianObsidian CLI
>sync my vaultGit CLI
>use git to store my vaultGit CLI
>move this note to...MCP + backlink repair

Not a fit for

×General markdown editing (no vault context)
×Non-Obsidian file management
×Web-based Obsidian Publish tasks

Workflow Patterns

Three patterns for combining MCP and Obsidian in a single session.

1

Search, then open

Search for a note through MCP, read it, then open it in Obsidian for visual editing.

1.MCP: search_notes
2.MCP: read_note
3.App: open in Obsidian
2

Choose a backend

File operations use MCPVault. Actions that need the running app use Obsidian CLI, with obsidian:// URIs as fallback.

1.Read the request
2.Choose MCP or Obsidian CLI
3.Run the operation
3

Review and patch

Write a draft via MCP, review in Obsidian, then patch corrections back through MCP.

1.MCP: write_note
2.App: review in editor
3.MCP: patch_note

Safety Defaults

Prefer MCP Writes

File mutations go through MCPVault path validation. Destructive tools require explicit confirmation parameters.

Confirm Destructive Actions

Deletes and moves require explicit path confirmation parameters, preventing accidental data loss.

Structured command arguments

Commands pass argument arrays instead of building shell command strings from note content.

Sandbox by Default

MCP tools are scoped to the vault root. Path traversal is blocked at the server level.

Quick Start

Install the skill to teach your AI assistant the Obsidian workflow.

Skill folder structure
.claude/
  skills/
    obsidian/
      SKILL.md                  # Gotchas, error recovery, index
      resources/
        tool-patterns.md        # Per-tool response shapes and recipes
        obsidian-conventions.md # Vault structure, wikilinks, tags
        git-sync.md             # Git backup/sync workflows
SKILL.md frontmatter
---
name: obsidian
description: >
  Activate when the user mentions their
  Obsidian vault, notes, tags, frontmatter,
  daily notes, backup, or sync. Route
  operations across MCP, Obsidian CLI/app
  actions, and git sync with safe defaults.
metadata:
  version: "2.2"
  author: bitbonsai
---

Install the skill

Add routing instructions for MCPVault, Obsidian CLI, and Git.

Installation