User Story & Vision

"Install the extension..."
uvx obsidian-mcp
"...and Claude can access your Obsidian vault."

I. The Problem

You want Claude to help you with your notes. But:

Current options suck:
What we want:

II. The User

The Knowledge Worker

Who: Someone who uses Obsidian for notes, research, writing

Context: Has a vault with hundreds/thousands of notes

Wants: Claude to help them find, synthesize, and create notes

Has: Claude Desktop, Obsidian, basic command line comfort

Barrier: Doesn't want to install plugins or configure things

III. The User Journey

journey title User's First Experience section Discovery Hears about obsidian-mcp: 3: User Reads README: 4: User Sees "uvx obsidian-mcp": 5: User section Installation Runs uvx command: 5: User Server starts: 5: User Claude Desktop detects it: 5: User section First Use Asks Claude about their notes: 4: User Claude lists their vaults: 5: User Claude searches their notes: 5: User Claude summarizes findings: 5: User section Power Use Creates note via Claude: 5: User Opens note in Obsidian: 5: User Feels productive: 5: User

IV. What Success Looks Like

Step User Action Result
1 Run uvx obsidian-mcp Server starts, finds vaults automatically
2 "What vaults do I have?" Claude lists all discovered vaults
3 "Search for notes about X" Claude returns matching notes with snippets
4 "Read the note about Y" Claude reads and summarizes the note
5 "Create a new note summarizing..." Claude creates note in vault
6 "Open that in Obsidian" Obsidian app opens to the note

V. Success Metrics

<30s
Install to first query
0
Config files to edit
0
Obsidian plugins required

VI. Example Conversations

Research Assistant

User: "I'm writing about climate change. What notes do I have on this topic?"

Claude: *searches vault* "I found 12 notes mentioning climate change. The most relevant are..."

User: "Summarize the key points from those notes"

Claude: *reads notes* "Based on your notes, here are the main themes..."

User: "Create a new note with that summary"

Claude: *creates note* "Done. Want me to open it in Obsidian?"

Daily Notes

User: "Open my daily note"

Claude: *triggers obsidian://daily* "Opening today's daily note in Obsidian"

User: "What did I write yesterday?"

Claude: *reads yesterday's daily note* "Yesterday you wrote about..."

Knowledge Graph

User: "What notes link to my 'Project Ideas' note?"

Claude: *searches for [[Project Ideas]]* "Found 8 notes that link to it..."

User: "Which of those are tagged #active?"

Claude: *filters* "3 of them have the #active tag..."

VII. Why Hybrid (Filesystem + URI)?

flowchart TB subgraph "Option 1: REST API Plugin" P1[Install plugin] P2[Configure API key] P3[Keep Obsidian running] P4[Network overhead] end subgraph "Option 2: Pure Filesystem" F1[Direct file access] F2[Works offline] F3[Can't trigger actions] F4[No live sync] end subgraph "Option 3: Hybrid ✓" H1[Filesystem for data] H2[URI for actions] H3[Best of both] H4[Zero plugins] end style H1 fill:#064e3b style H2 fill:#064e3b style H3 fill:#064e3b style H4 fill:#064e3b

VIII. What We're Building

Phase Deliverable Validates
1 Vault discovery POC obsidian.json parsing works cross-platform
2 Filesystem read/write Can safely read/write markdown files
3 URI integration Can trigger Obsidian actions cross-platform
4 obsidian-sdk package Clean SDK that others can use
5 MCP server Full Claude Desktop integration
6 PyPI + uvx release One-command install works