obsidian-mcp/README.md

# 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:
   ```bash
   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](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop).

### Manual Installation

```bash
# 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:

```json
{
  "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

```bash
# 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](https://modelcontextprotocol.io)
- [MCPB Bundle Format](https://github.com/anthropics/mcpb)
- [Obsidian CLI Documentation](https://help.obsidian.md/CLI)