# Second Brain + Obsidian MCP Setup Guide

## Quick Start

### 1. Start Obsidian
```bash
~/.local/bin/obsidian
```
Or from Applications menu if you have desktop access.

### 2. Open This Vault
- In Obsidian, click "Open folder as vault"
- Select `/workspace/second-brain/`

### 3. Install Local REST API Plugin
1. Go to Settings → Community plugins
2. Click "Browse" and search for "Local REST API"
3. Install and enable it
4. Go to the plugin settings
5. **Copy the API Key** (you'll need this!)

### 4. Configure MCP Server
Edit `/workspace/second-brain/.env`:
```
OBSIDIAN_API_KEY=paste_your_api_key_here
```

### 5. Test the Setup
```bash
./start-mcp.sh
```

If successful, you'll see:
```
✅ Obsidian Local REST API is reachable
Starting Obsidian MCP Server...
```

---

## Architecture

```
┌─────────────────────────────────────┐
│ Obsidian Desktop                    │
│ + Local REST API Plugin             │
│ (Port 27123)                        │
└─────────────────────┬───────────────┘
                      │ HTTP API
                      ↓
┌─────────────────────────────────────┐
│ obsidian-mcp-server                 │
│ (MCP Protocol)                      │
└─────────────────────┬───────────────┘
                      │ MCP (stdio/http)
                      ↓
┌─────────────────────────────────────┐
│ AI Agent (Bumblebee/Claude)         │
│ → Can read/write/search vault!      │
└─────────────────────────────────────┘
```

---

## Available MCP Tools

Once connected, the AI agent can use:

| Tool | Description |
|------|-------------|
| `obsidian_read_note` | Read note content and metadata |
| `obsidian_update_note` | Append, prepend, or overwrite notes |
| `obsidian_global_search` | Search entire vault |
| `obsidian_list_notes` | List files in a directory |
| `obsidian_manage_tags` | Add/remove/list tags |
| `obsidian_manage_frontmatter` | Manage YAML frontmatter |
| `obsidian_delete_note` | Delete a note |
| `obsidian_search_replace` | Find and replace in notes |

---

## Headless Operation (Server)

For running on a headless server (no display):

### Option A: Virtual Display (Xvfb)
```bash
# Install Xvfb
sudo apt install xvfb

# Start Obsidian with virtual display
xvfb-run -a ~/.local/bin/obsidian --no-sandbox &
```

### Option B: VNC/Remote Desktop
```bash
# Start a VNC server, then run Obsidian inside it
```

### Option C: X11 Forwarding
```bash
# SSH with X11 forwarding
ssh -X user@server
~/.local/bin/obsidian
```

---

## Files

- `.env` — API key and config (DO NOT COMMIT)
- `start-mcp.sh` — Start the MCP server
- `dream-sync.sh` — Nightly synthesis script
- `.dreamrc` — Dream sync configuration

---

## Troubleshooting

**"Cannot reach Obsidian Local REST API"**
- Make sure Obsidian is running
- Check that Local REST API plugin is enabled
- Verify the port (default: 27123)

**"API key invalid"**
- Regenerate the key in Obsidian plugin settings
- Update `.env` with new key

**Obsidian won't start (headless)**
- Use `xvfb-run` for virtual display
- Or run with `--no-sandbox` flag

---

Created: 2026-04-26