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

```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)