Obsidian Skill

Combines MCP server safety with Obsidian CLI context.
One skill that routes each operation to the right backend.

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

Find any note instantly

Full-text search across your entire vault with relevance ranking. Just describe what you're looking for.

Organize with smart tags

Add, remove, and bulk-manage tags and frontmatter across hundreds of notes in seconds.

Edit notes safely

Read, write, and patch notes with atomic operations. Path sandboxing prevents accidental changes outside your vault.

Sync across devices

Optional git-based sync keeps your vault backed up and available everywhere — no paid subscription required.

Routing Matrix

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

Operation MCP Obsidian CLI Git
Read note ✓ — —
Write / patch note ✓ — —
Search vault ✓ — —
Manage tags / frontmatter ✓ — —
Move / rename files ✓ — —
Open note in Obsidian — ✓ —
Trigger plugin commands — ✓ —
Export to PDF — ✓ —
Sync vault across devices — — ✓
Automated backup — — ✓

Flow Cheat Sheet

The skill routes by intent. MCP is the safe default for vault edits, Obsidian context is used for app-specific actions, and Git CLI handles sync/backup.

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/moves.
  • -Obsidian context for app/editor/plugin-specific behavior.
  • -Git CLI for sync, backup, and versioning actions.

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 all file I/O: reading, writing, searching, patching, and organizing notes. Enforces path sandboxing, validates inputs, and performs atomic operations. The safe default for any vault mutation.

Obsidian CLI

Bridges the gap for operations that need the running desktop app: opening notes in the editor, triggering plugin commands, exporting to PDF via Obsidian URI schemes.

Git Sync

Plain git for vault syncing across devices. No Obsidian Sync subscription required. Works headlessly via cron, launchd, or CI — no app needs to be running.

Git-Based Vault Sync

Free alternative to Obsidian Sync — expand for setup details

How it works

An Obsidian vault is just a folder of markdown files. You can git init inside it, add a remote, and push/pull like any repo. No proprietary format, no paid service.

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

  • - Not real-time — git syncs on commit intervals, not instantly
  • - Merge conflicts — editing the same note on two devices before syncing requires manual resolution
  • - Large binaries — images and PDFs aren't great for git; use .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 Obsidian Obsidian CLI
> sync my vault Git CLI
> use git to store my vault Git CLI
> move this note to... MCP

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

Sequential Orchestration

Chain MCP reads into app actions. Search for a note via MCP, then open it in Obsidian for visual editing.

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

Context-Aware Selection

The skill picks the right backend automatically. File operations route through MCP; app-context actions use Obsidian URI schemes.

1. Analyze user intent
2. Route to MCP or App
3. Execute with safety checks
3

Iterative Refinement

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

All file mutations go through the MCP server, which validates paths, confirms targets, and performs atomic writes.

Confirm Destructive Actions

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

No Shell Interpolation

Commands use structured arguments, never string-interpolated shell input. No injection vectors.

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.0"
  author: bitbonsai
---

Ready to get started?

Install MCP-Vault and connect your vault to any AI assistant.

Install Now