Add Obsidian MCP server setup

2026-04-26 06:03:05 +02:00
parent 8036d6443c
commit e6f334ce15
4 changed files with 198 additions and 0 deletions
@@ -0,0 +1,135 @@
+# 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