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

Installing custom desktop extensions:

1. Build or obtain the .mcpb bundle file:

   npm run build
   npm run pack
   

2. Open Claude Desktop and navigate to Settings > Extensions

3. Click "Advanced settings" to access the Extension Developer section

4. Click "Install Extension…" and select the obsidian-mcp.mcpb file

5. Follow the prompts to configure the extension:

   • Set your vault_name (the name of your Obsidian vault)
   • Claude Desktop will encrypt sensitive configuration using your OS's secure storage

6. The extension will appear in your installed extensions list and tools will be available in Claude

For more details, see Getting started with local MCP servers on Claude Desktop.

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.

Via Claude Desktop Extensions UI:

After installing the extension through Claude Desktop (see installation steps above), you'll be prompted to configure:

• vault_name: The name of your Obsidian vault (required)

Manual configuration (advanced):

If configuring manually in Claude Desktop's MCP servers configuration:

{
  "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 20 MCP tools covering:

• File Operations (8 tools): create_note, read_note, append_to_note, prepend_to_note, delete_note, move_note, rename_note, open_note
• Search & Discovery (11 tools): search, list_backlinks, list_links, list_unresolved_links, list_tags, list_tag_counts, list_aliases, list_alias_counts, list_properties, list_property_counts, get_property_values
• Tasks & Properties (planned): Task management and property operations (User Story 3)

See full tool documentation in the manifest.json file or via tools/list MCP call.

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