obsidian-mcp/specs/001-obsidian-mcp-bundle/quickstart.md

Quickstart: Obsidian MCP Bundle

Purpose: Validate the implementation works end-to-end

Prerequisites

• Obsidian application installed and running
• At least one Obsidian vault configured
• Obsidian CLI accessible in PATH (obsidian help works)
• Node.js >= 18.0.0 installed

Setup

1. Install dependencies:

   npm install
   

2. Build the bundle:

   npm run build
   

3. Run tests:

   npm test
   

4. Create the .mcpb package:

   npm run pack
   # Outputs: obsidian-mcp.mcpb
   

Local Testing (Before Packaging)

1. Start MCP Server Manually

node dist/index.js

Server is now listening on stdin/stdout for JSON-RPC messages.

2. Send Test Messages

In a separate terminal, pipe JSON-RPC requests:

# Initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node dist/index.js

# Expected: {"jsonrpc":"2.0","id":1,"result":{...}}

# List tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node dist/index.js

# Expected: {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}

3. Test a Tool

Create a test note:

echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"obsidian_create_note","arguments":{"name":"Test Note","content":"# Test\n\nThis is a test note."}}}' | OBSIDIAN_VAULT="My Vault" node dist/index.js

# Expected: {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\"success\":true,...}"}]}}

Verify in Obsidian that "Test Note.md" was created.

Installation in Claude Desktop

1. Open the .mcpb file in Claude Desktop:

   • Double-click obsidian-mcp.mcpb
   • Or drag and drop into Claude Desktop

2. Configure vault:

   • Claude Desktop will prompt for vault name
   • Enter your Obsidian vault name (e.g., "My Vault")

3. Test in conversation:

   User: "Create a new note called 'Meeting Notes' with the content 'Discuss Q1 goals'"
   
   Claude: [Uses obsidian_create_note tool]
   "I've created a new note called 'Meeting Notes' with that content."
   

4. Verify in Obsidian:

   • Open Obsidian
   • Check that "Meeting Notes.md" exists with correct content

Validation Checklist

Run through these scenarios to verify functionality:

✅ Basic File Operations (P1)

• Create a new note: "Create a note called Test"
• Read a note: "What does my Test note say?"
• Append to a note: "Add 'new line' to Test note"
• Delete a note: "Delete the Test note"

Expected: All operations complete in <3 seconds

✅ Search & Discovery (P2)

• Search vault: "Find all notes mentioning 'project'"
• List backlinks: "What notes link to my Projects note?"
• List tags: "What are my most used tags?"
• Unresolved links: "Show me broken links"

Expected: Search completes in <5 seconds for vaults with <10k notes

✅ Tasks (P3)

• List tasks: "Show me all my incomplete tasks"
• Toggle task: "Mark the first task as done"
• Daily tasks: "Show tasks from my daily note"

Expected: Task operations complete in <3 seconds

✅ Properties (P3)

• Set property: "Set the 'status' property to 'in-progress' on Test note"
• Read property: "What's the status property on Test note?"
• List properties: "What properties exist in my vault?"

Expected: Property operations complete in <3 seconds

✅ Vault Navigation (P4)

• List files: "How many notes do I have?"
• Vault info: "Tell me about my vault"
• Recent files: "What notes did I recently open?"

Expected: Navigation queries complete in <3 seconds

✅ Error Handling

• Obsidian not running: Stop Obsidian, try create note

  • Expected: "Obsidian application is not running. Please start Obsidian and try again."

• Ambiguous note name: Create two notes with same name in different folders, try to read by name only

  • Expected: Error listing all matching paths

• File not found: "Read a note called NonexistentNote"

  • Expected: "Note 'NonexistentNote' not found."

• Invalid vault: Configure with wrong vault name

  • Expected: "Vault '{name}' not found. Check your vault name in MCP settings."

✅ Protocol Compliance

• Initialize handshake completes
• tools/list returns 95 tools
• All tool responses are valid JSON
• stderr contains logs, stdout only has JSON-RPC
• Graceful shutdown on EOF/exit

✅ Performance

• File operations: <3s (SC-001)
• Search operations: <5s for 10k notes (SC-002)
• No timeout errors under normal conditions

✅ Cross-Platform

Test on all supported platforms:

• macOS (Darwin)
• Windows (win32)
• Linux

Common Issues & Solutions

"Obsidian not found in PATH"

Solution: Add Obsidian CLI to your PATH or specify full path in manifest.json mcp_config.

{
  "command": "/Applications/Obsidian.app/Contents/MacOS/obsidian",
  ...
}

"Vault not found"

Solution: Use exact vault name as shown in Obsidian. Check with obsidian vaults.

"Permission denied"

Solution: Ensure vault directory has read/write permissions for current user.

"Timeout errors"

Solution: Check Obsidian performance. Large vaults (>10k notes) may need optimization.

Debug Mode

Enable verbose logging:

OBSIDIAN_MCP_DEBUG=true node dist/index.js

Logs will be written to stderr with full request/response details (sanitized).

Next Steps After Validation

1. Package for distribution: npm run pack
2. Test on different vaults: Large vaults, different structures
3. Test all 95 tools: Comprehensive tool validation
4. Performance benchmarking: Measure against success criteria
5. Security audit: Verify input sanitization and error messages

Success Criteria Verification

• ✅ SC-001: Basic file operations < 3s
• ✅ SC-002: Search queries < 5s (up to 10k notes)
• ✅ SC-003: 100% JSON validity (validate with JSON parser)
• ✅ SC-004: Error messages enable self-resolution (test error scenarios)
• ✅ SC-005: Single-click install in Claude Desktop
• ✅ SC-006: 95% CLI command coverage (90 of 95 tools implemented)
• ✅ SC-007: AI selects correct tool on first attempt (user testing)
• ✅ SC-008: Works on macOS, Windows, Linux

Quick Start Summary

# 1. Build
npm install && npm run build

# 2. Test locally
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}' | OBSIDIAN_VAULT="My Vault" node dist/index.js

# 3. Package
npm run pack

# 4. Install in Claude Desktop
# Double-click obsidian-mcp.mcpb

# 5. Validate
# Ask Claude: "Create a note called Test with content Hello"
# Check Obsidian for Test.md

If all validation steps pass, the implementation is ready for production use! 🎉