# claude-obsidian MCP

> A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects **Claude Desktop** to your **Obsidian vault** — making Obsidian the single source of truth for all your PM work: PRDs, processes, Jira notes, meeting notes, and ideas.

---

## What This Enables

Once installed, you can talk to Claude naturally and it will automatically manage your Obsidian notes:

| Say to Claude | What happens |
|---|---|
| _"Create a PRD for the new onboarding flow"_ | Creates a structured PRD in `PRDs/` |
| _"Log notes for PROJ-123, it's about payment timeout"_ | Creates `Jira/PROJ-123.md` with full context |
| _"Create meeting notes for today's sprint planning"_ | Creates a structured meeting note in `Meetings/` |
| _"Capture this thought: we should rethink the checkout UX"_ | Saves to `Ideas/` with timestamp |
| _"Document the deployment process"_ | Creates a process SOP in `Processes/` |
| _"Search my notes for authentication"_ | Full-text search across your entire vault |
| _"Show me my vault overview"_ | Lists all folders and note counts |
| _"Set up my vault structure"_ | Creates all folders + index notes in one shot |

---

## Prerequisites

### 1. Obsidian + Local REST API Plugin

1. Open **Obsidian**
2. Go to **Settings → Community plugins → Browse**
3. Search for **"Local REST API"** and install it
4. Enable it, then go to **Settings → Local REST API**
5. Copy the **API Key** shown there — you'll need it in Step 3 below
6. Leave Obsidian open while using Claude (the plugin serves on `localhost:27124`)

> **Note:** Your vault is at `/Users/harunzeybek/Documents`

### 2. Node.js

Requires Node.js 18 or later. Check with:
```bash
node --version
```

---

## Installation

### Step 1 — Clone & Build

```bash
git clone https://github.com/harunzybk/claude-obsidian.git
cd claude-obsidian
npm install
npm run build
```

### Step 2 — Note the full path to the built server

```bash
pwd
# e.g. /Users/harunzeybek/Repositories/claude-obsidian
```

The server binary is at: `<that path>/dist/index.js`

### Step 3 — Configure Claude Desktop

Open your Claude Desktop config file:

```bash
open ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

Add the following inside the `"mcpServers"` object (replace `YOUR_API_KEY` with the key from Step 1):

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/Users/harunzeybek/Repositories/claude-obsidian/dist/index.js"],
      "env": {
        "OBSIDIAN_API_KEY": "YOUR_API_KEY",
        "OBSIDIAN_VAULT_PATH": "/Users/harunzeybek/Documents",
        "OBSIDIAN_USE_HTTPS": "true"
      }
    }
  }
}
```

> If the file doesn't exist yet, create it with the full content above.

### Step 4 — Restart Claude Desktop

Quit and reopen Claude Desktop. You should see **"obsidian"** listed as a connected MCP server (look for the 🔌 icon or check Settings → Developer).

### Step 5 — Initialize Your Vault Structure

In Claude Desktop, say:

> _"Set up my Obsidian vault structure"_

Claude will create all folders and index notes automatically.

---

## Available Tools

### Note Operations
| Tool | Description |
|------|-------------|
| `create_note` | Create a new note at any path |
| `read_note` | Read a note's full content |
| `update_note` | Replace a note's content |
| `append_to_note` | Add content to the end of a note |
| `delete_note` | Delete a note |
| `list_notes` | List files in a folder |

### Search
| Tool | Description |
|------|-------------|
| `search_notes` | Full-text search across the vault |
| `search_by_tag` | Find notes by Obsidian `#tag` |

### Vault Management
| Tool | Description |
|------|-------------|
| `list_folders` | List folders |
| `create_folder` | Create a new folder |
| `get_vault_overview` | Top-level structure + note counts |

### PM Templates
| Tool | Description |
|------|-------------|
| `create_prd` | Structured PRD with goals, requirements, success metrics |
| `create_process_doc` | SOP / process documentation |
| `log_jira_note` | Rich Jira ticket context notes |
| `capture_thought` | Quick idea / brain dump |
| `create_meeting_note` | Meeting notes with agenda + action items |
| `create_project_note` | Project overview and tracking |
| `setup_vault_structure` | Initialize all folders + index notes |

---

## Vault Folder Structure

```
Your Vault (Documents/)
├── Home.md               ← Start here — links to everything
├── PRDs/                 ← Product Requirements Documents
├── Processes/            ← SOPs and process documentation
├── Jira/                 ← Jira ticket context notes
├── Meetings/             ← Meeting notes (YYYY-MM-DD-title.md)
├── Ideas/                ← Quick thoughts and brain dumps
├── Projects/             ← Project tracking notes
└── Resources/            ← Reference materials
```

---

## Troubleshooting

**Claude says it can't connect to Obsidian**
- Make sure Obsidian is open
- Check that "Local REST API" plugin is enabled in Obsidian
- Verify the API key in your `claude_desktop_config.json` is correct

**"Cannot find module" error**
- Run `npm run build` again in the project folder
- Make sure the path in `claude_desktop_config.json` points to `dist/index.js`, not `src/index.ts`

**HTTPS certificate error**
- Set `"OBSIDIAN_USE_HTTPS": "false"` in your config (HTTP mode)

---

## Development

```bash
npm run dev      # Watch mode — recompiles on change
npm run build    # Production build
npm start        # Run the compiled server
```

---

## License

MIT © [harunzybk](https://github.com/harunzybk)