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 and running

Important: The Obsidian application must be open and running before using any MCP tools. The CLI used by this bundle communicates with the running Obsidian instance. If Obsidian is not running, commands will launch the GUI instead of executing — start Obsidian first, then use the MCP tools.

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 28 MCP tools organized into three categories:

File Operations (8 tools)

• obsidian_create_note - Create a new note with optional content and properties
• obsidian_read_note - Read the content of an existing note
• obsidian_append_to_note - Add content to the end of a note
• obsidian_prepend_to_note - Add content to the beginning of a note
• obsidian_delete_note - Delete a note from the vault
• obsidian_move_note - Move a note to a different folder
• obsidian_rename_note - Rename a note (changes filename)
• obsidian_open_note - Open a note in Obsidian

Search & Discovery (12 tools)

• obsidian_search - Search vault for text with filters and formatting options
• obsidian_get_backlinks - Get all notes that link to a specific note
• obsidian_list_outgoing_links - List all links from a note to other notes
• obsidian_list_unresolved_links - Find all broken/non-existent links in vault
• obsidian_list_tags - List all tags in vault or specific note
• obsidian_search_by_tag - Find all notes containing a specific tag
• obsidian_get_tag_count - Count how many notes use a specific tag
• obsidian_list_aliases - List all aliases in vault or for a specific note
• obsidian_list_properties - List all properties used in the vault
• obsidian_get_property_count - Get usage count for a specific property

Task & Property Management (8 tools)

• obsidian_list_tasks - List all tasks with filtering by status, file, path, or tags
• obsidian_toggle_task - Toggle a task between done and todo states
• obsidian_mark_task_done - Mark a task as completed
• obsidian_mark_task_todo - Mark a task as incomplete
• obsidian_update_task_status - Set custom status character for a task (-, >, !, ?)
• obsidian_get_property - Read a single property value from a file
• obsidian_set_property - Set or update a property on a file
• obsidian_remove_property - Remove a property from a file

For detailed parameter information and schemas, see the manifest.json file or use the MCP tools/list 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

The Obsidian application must be running before using any MCP tools. The CLI communicates with the running Obsidian instance — if Obsidian is closed, commands will launch the GUI app instead of executing.

Fix: Open the Obsidian application and wait for it to fully load, then retry the operation.

"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