obsidian-vault

Obsidian Vault

Use the 17 MCP tools in the literature profile plus Claude's built-in tools (Read, Write, Edit, Grep, Bash, Glob) for all vault work.

Core MCP Tools

• obsidian_read_file / obsidian_write_file — read and write vault notes
• obsidian_search — full-text search across the vault
• obsidian_update_properties — safely merge/replace YAML frontmatter

File Management

To list files: use obsidian_search with an empty query, or use the Glob tool with the vault path.

To delete a file: use Bash → Remove-Item "vault_path\relative\path.md" (Windows) or rm.

To move/rename a file: use Bash → Move-Item (Windows) or mv. If Obsidian is open, use the obsidian-cli skill to preserve wikilink integrity.

To batch-move files: use Bash with a loop or Get-ChildItem | Move-Item.

Graph Maintenance

To analyse the wikilink graph:

1. Use obsidian_search with query="" to list all .md files.
2. For each file, use obsidian_read_file to extract [[wikilinks]] with regex \[\[([^\]]+)\]\].
3. Build an edge list and identify orphans (nodes with no in-links) and dead links (targets that don't exist as files).
4. Report findings. Suggest obsidian_write_file fixes for broken links.

To find orphans: collect all filenames, collect all link targets, subtract linked from all.

To find broken links: collect all link targets, subtract existing filenames.

To add wikilinks: use obsidian_read_file + obsidian_write_file with the updated content.

Vault Health (Lint)

Run this sequence:

1. obsidian_search with query="" — get all notes.
2. Read each note with obsidian_read_file and check:
   • Missing required frontmatter fields (type, title, tags).
   • Dead [[links]] pointing to non-existent notes.
   • Notes with no outgoing or incoming links (orphans).
3. Report a structured issues list grouped by type.

Wiki Maintenance

To update the wiki index (index.md):

1. Use obsidian_search to list notes by tag or folder.
2. Build a markdown catalogue grouped by tag.
3. Use obsidian_write_file to write the catalogue between <!-- obsidian-vault:index:start --> and <!-- obsidian-vault:index:end --> markers.

To append a wiki log entry (log.md):

1. Use obsidian_read_file to read existing log.md (or create if absent).
2. Prepend a new ## YYYY-MM-DD entry with the summary and touched paths.
3. Use obsidian_write_file to save.

Schema Validation

To validate frontmatter schema:

1. Use obsidian_search to find notes by folder prefix (e.g. sources/, entities/).
2. For each note, use obsidian_read_file and parse the YAML frontmatter block.
3. Check required fields: sources/ → {type, title, tags}, entities/ → {type, title, sources}.
4. Report missing or invalid fields.

To apply schema defaults:

1. For notes missing required fields, use obsidian_update_properties with merge_mode="merge" to fill in defaults.
2. Use dry_run=true first to preview.

Bulk Editing (Edit Plans)

To preview a multi-file edit:

1. Collect the list of files and planned changes.
2. Use obsidian_read_file on each, show before/after diffs inline.
3. Ask the user to confirm before writing.

To apply:

1. For each file, use obsidian_write_file or obsidian_update_properties.
2. Keep a backup list of original content for rollback.

To rollback: restore each file from the backup content using obsidian_write_file.

Note Creation with Templates

To create a note with a template:

1. Use obsidian_search in the templates folder (check .obsidian/templates.json for path).
2. Use obsidian_read_file to load the template.
3. Substitute {{title}}, {{body}}, {{status}} and Templater tokens (<% tp.date.now(...) %>).
4. Merge template frontmatter with supplied properties (supplied properties win).
5. Use obsidian_write_file to write the note.

Safety

• Always use dry_run=true before broad mutations.
• Never write outside the vault root.
• Prefer obsidian_update_properties for frontmatter edits — it preserves body content.
• When Obsidian desktop is open, prefer the obsidian-cli skill for moves and renames.
• To generate AI summaries for literature notes, use the obsidian-ai-summary skill.

Eval Scenarios

• Trigger: "Audit my vault for orphan notes and dead links." Expected: use obsidian_search/obsidian_read_file, report grouped issues, and avoid writes.
• Trigger: "Add missing type and title fields across literature notes." Expected: preview broad changes first with dry_run=true, then use obsidian_update_properties only after confirmation. Must not rewrite note bodies.
• Trigger: "Move this note while Obsidian is open." Expected: switch to obsidian-cli for move/rename so wikilinks are updated. Must not use raw filesystem moves in that case.

---

中文说明

使用 17 个 MCP 工具加上 Claude 内置工具处理所有 vault 操作。图谱分析、lint 检查、wiki 维护、schema 验证和批量编辑现在通过 obsidian_search + obsidian_read_file + obsidian_write_file 组合完成，不再依赖独立的 MCP 工具。