Obsidian MCP - Development Roadmap

Project Law: No implementation until clear POC and validation. All work starts with a GitHub issue.

Overview

gantt title Development Phases dateFormat YYYY-MM-DD section Phase 1 Vault Discovery POC :p1, 2025-01-27, 3d section Phase 2 Filesystem Read/Write POC :p2, after p1, 3d section Phase 3 URI Scheme POC :p3, after p2, 2d section Phase 4 obsidian-sdk Package :p4, after p3, 5d section Phase 5 MCP Server :p5, after p4, 4d section Phase 6 PyPI + uvx Release :p6, after p5, 2d section Phase 7 AI Metadata Assistant :p7, after p6, 5d

Phase 1: Vault Discovery

Goal: Prove we can auto-discover Obsidian vaults cross-platform

#1 - Spike: Parse obsidian.json on Linux

Read ~/.config/obsidian/obsidian.json and extract vault paths.

spike
#2 - Spike: Test obsidian.json on macOS

Verify ~/Library/Application Support/obsidian/obsidian.json path works.

spike
#3 - Spike: Test obsidian.json on Windows

Verify %APPDATA%/obsidian/obsidian.json path works.

spike
#4 - Document vault discovery findings

Update architecture.html with learnings from spikes.

documentation architecture

Phase 2: Filesystem Operations

Goal: Prove we can safely read/write notes

#5 - Spike: Read markdown files from vault

List and read .md files. Handle subdirectories. Test with large vaults.

spike
#6 - Spike: Write markdown files safely

Create new notes. Update existing. Handle conflicts. Test atomic writes.

spike
#7 - Spike: Full-text search implementation

Compare grep-based vs. in-memory index vs. SQLite FTS. Pick best approach.

spike
#8 - Spike: Frontmatter parsing

Decide if/how to parse YAML frontmatter. Test with various formats.

spike

Phase 3: URI Scheme

Goal: Prove we can trigger Obsidian actions cross-platform

#9 - Spike: obsidian:// URI on Linux

Test opening URIs via xdg-open. Verify Obsidian responds.

spike
#10 - Spike: obsidian:// URI on macOS

Test opening URIs via open command. Verify Obsidian responds.

spike
#11 - Spike: obsidian:// URI on Windows

Test opening URIs via start command. Verify Obsidian responds.

spike
#12 - Document URI capabilities and limitations

Update architecture.html with what URIs can/can't do.

documentation

Phase 4: SDK Package

Goal: Create clean, reusable obsidian-sdk package

#13 - Create obsidian-sdk package structure

Set up Poetry project, define public API, write basic structure.

sdk
#14 - Implement VaultDiscovery class

Cross-platform vault detection from obsidian.json.

sdk
#15 - Implement NotesManager class

Read, write, list, delete notes. Handle paths safely.

sdk
#16 - Implement SearchEngine class

Full-text search with the approach chosen in spike #7.

sdk
#17 - Implement URIHandler class

Cross-platform obsidian:// URI launching.

sdk
#18 - Write SDK tests

Unit tests for all SDK components. Mock filesystem for CI.

sdk

Phase 5: MCP Server

Goal: Wrap SDK with MCP tools for Claude Desktop

#19 - Create MCP server structure

Set up Poetry project with MCP SDK dependency. Define tools.

server
#20 - Implement list_vaults tool

MCP tool that returns all discovered vaults.

server
#21 - Implement note read/write tools

list_notes, read_note, write_note, delete_note tools.

server
#22 - Implement search_notes tool

Full-text search across vault with snippets.

server
#23 - Implement open_in_obsidian tool

Trigger obsidian:// URI to open notes in app.

server
#24 - Test with Claude Desktop

End-to-end testing with actual Claude Desktop.

server spike

Phase 6: Release

Goal: Publish to PyPI, verify uvx works

#25 - Publish obsidian-sdk to PyPI

Configure Poetry for PyPI. Publish package.

sdk
#26 - Publish obsidian-mcp to PyPI

Configure Poetry for PyPI. Set up entry point for uvx.

server
#27 - Test uvx obsidian-mcp flow

Fresh machine test. Verify one-command install works.

spike
#28 - Update README with final instructions

Polish documentation for public release.

documentation

Phase 7: AI-Powered Metadata Assistant

Goal: Complement Dataview with AI-native metadata capabilities

Value Proposition: Dataview is a read-only query engine. Obsidian MCP becomes an AI-powered metadata assistant—suggesting, writing, and managing frontmatter that Dataview can't modify.
#58 - Add get_vault_schema tool

Discover all frontmatter keys and common values used across the vault. Enables Claude to understand the user's existing metadata patterns.

server
#57 - Add update_frontmatter tool

Update specific frontmatter fields without touching note body. Add tags, change status, set dates—programmatically.

server
#59 - Add suggest_frontmatter tool

Analyze note content and suggest appropriate frontmatter based on vault patterns. Returns suggestions with confidence levels.

server
#56 - Document AI Metadata Assistant on GitHub Pages

Add value proposition, Dataview comparison, and user workflow examples to the website.

documentation

Issue Summary

Phase Issues Focus
1 - Discovery #1-4 Vault auto-detection
2 - Filesystem #5-8 Note read/write/search
3 - URI #9-12 Obsidian actions
4 - SDK #13-18 obsidian-sdk package
5 - Server #19-24 MCP server
6 - Release #25-28 PyPI + uvx
7 - AI Metadata #56-59 Frontmatter tools