Obsidian MCP Bundle

An MCP (Model Context Protocol) Bundle that exposes Obsidian CLI capabilities to AI assistants, enabling conversational note management through natural language.

Features

• 📝 File Operations: Create, read, update, delete notes
• 🔍 Search & Discovery: Full-text search, tag queries, backlink navigation
• ✅ Task Management: Create, update, and track tasks
• 🏷️ Properties & Metadata: Manage note properties, tags, and aliases
• 📅 Daily Notes: Create and navigate daily notes
• 🔖 Bookmarks: Manage bookmarked notes
• 🎨 Customization: Plugin and theme management
• 🔄 Vault Navigation: List files, folders, and navigate hierarchies

Installation

Prerequisites

• Node.js >= 18.0.0
• Obsidian CLI installed and configured
• Obsidian application installed

Install via Claude Desktop

1. Download the latest .mcpb file from releases
2. Open Claude Desktop settings
3. Add the bundle to your MCP servers configuration
4. Configure your vault name in the settings

Manual Installation

# Install dependencies
npm install

# Build the bundle
npm run build

# Package as .mcpb file
npm run pack

Configuration

The bundle requires a vault_name parameter to target your Obsidian vault:

{
  "mcpServers": {
    "obsidian-mcp": {
      "bundle": "path/to/obsidian-mcp.mcpb",
      "user_config": {
        "vault_name": "MyVault"
      }
    }
  }
}

Usage Examples

With Claude Desktop

You: "Create a new note called 'Meeting Notes' with today's date"
Assistant: [Uses obsidian_create_note tool]

You: "Search for all notes about project planning"
Assistant: [Uses obsidian_search tool]

You: "Add a task to my daily note: Review PR #123"
Assistant: [Uses obsidian_add_task tool]

Available Tools

The bundle provides 95+ MCP tools covering:

• File Operations: create_note, read_note, append_to_note, delete_note, move_note, rename_note, open_note, get_file_info
• Search: search (content), search_tags, search_properties
• Links: get_backlinks, get_outbound_links, get_unresolved_links
• Tasks: add_task, list_tasks, update_task
• Properties: get_properties, add_property, update_property, remove_property
• Tags: get_tags, add_tag, remove_tag
• Navigation: list_files, list_folders, get_folder_info
• Daily Notes: create_daily_note, goto_daily_note
• And more: templates, bookmarks, plugins, themes, history, sync

See full tool documentation in the contracts/tools.md file.

Development

# Install dependencies
npm install

# Run in development mode (watch for changes)
npm run dev

# Run tests
npm test

# Validate tool descriptions
npm run validate-tools

# Build for production
npm run build

Architecture

• Transport: stdio (JSON-RPC over standard input/output)
• Validation: Zod schemas for all tool parameters
• Error Handling: Graceful error messages with actionable guidance
• Timeout Management: 30-second default timeout for CLI commands
• Logging: Sanitized stderr-only logging (no stdout pollution)

Performance

• File operations: < 3 seconds
• Search queries: < 5 seconds (vaults up to 10,000 notes)
• CLI timeout: 30 seconds (configurable per command)

Platform Support

• macOS
• Windows
• Linux

License

MIT

Contributing

Contributions are welcome! Please ensure:

1. All tools follow MCP protocol standards
2. Input validation uses Zod schemas
3. Errors provide actionable messages
4. Tests pass with npm test
5. Tool descriptions are clear and complete

Troubleshooting

"Obsidian not running" error

Start the Obsidian application before using MCP tools.

"Vault not found" error

Ensure the vault_name in your configuration matches exactly (case-sensitive).

Timeout errors

Increase timeout in src/config/timeouts.ts for slow operations.

Resources

• MCP Protocol Specification
• MCPB Bundle Format
• Obsidian CLI Documentation