# obsidian-mcp

[![npm version](https://img.shields.io/npm/v/@zuchka/obsidian-mcp.svg)](https://www.npmjs.com/package/@zuchka/obsidian-mcp)
[![CI](https://github.com/zuchka/obsidian-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/zuchka/obsidian-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

MCP server for Obsidian. Wraps the [official Obsidian CLI](https://obsidian.md/help/cli) to expose 24 tools for reading, writing, searching, and managing your vault from Claude.

## Prerequisites

1. Obsidian ≥ 1.12 installed at `/Applications/Obsidian.app`
2. CLI registered: open Obsidian → click "Register CLI" prompt (adds `obsidian` to PATH)
3. Node.js ≥ 18

## Install via npm

```bash
npx @zuchka/obsidian-mcp
```

Or install globally for persistent use:

```bash
npm install -g @zuchka/obsidian-mcp
```

## Claude Desktop Setup

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@zuchka/obsidian-mcp"],
      "env": {
        "OBSIDIAN_VAULT": "My Vault"
      }
    }
  }
}
```

Restart Claude Desktop. The "obsidian" server will appear in the tool list.

## Claude Code Setup

```bash
claude mcp add obsidian npx -- -y @zuchka/obsidian-mcp
```

## Manual Install (from source)

```bash
git clone https://github.com/zuchka/obsidian-mcp
cd obsidian-mcp
npm install && npm run build
```

Then use the absolute path in your config:

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT": "My Vault"
      }
    }
  }
}
```

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `OBSIDIAN_VAULT` | (active vault) | Default vault when multiple exist |
| `OBSIDIAN_BINARY` | `/Applications/Obsidian.app/Contents/MacOS/Obsidian` | CLI binary path |

## Tools

| Tool | Description |
|---|---|
| `list_files` | List vault files, filter by folder/ext |
| `list_folders` | List vault folders as tree |
| `read_note` | Read note content by name or path |
| `create_note` | Create note (with optional template) |
| `append_note` | Append text to a note |
| `prepend_note` | Prepend text to a note |
| `move_note` | Move/rename note, updates all links |
| `delete_note` | Delete note (trash or permanent) |
| `search_vault` | Full-text and tag/property search |
| `get_properties` | Read YAML frontmatter |
| `set_property` | Set a frontmatter property |
| `remove_property` | Remove a frontmatter property |
| `list_tags` | List all tags sorted by count |
| `notes_by_tag` | Notes with a specific tag |
| `get_links` | Outgoing links from a note |
| `get_backlinks` | Notes linking to a note |
| `find_orphans` | Notes with zero links |
| `find_broken_links` | Unresolved wikilinks |
| `list_tasks` | All open tasks |
| `create_task` | Append a checkbox task to a note |
| `complete_task` | Mark a task done by file and line number |
| `read_daily_note` | Read today's (or a date's) daily note |
| `append_daily_note` | Append to today's daily note |
| `prepend_daily_note` | Prepend to today's daily note |