second-brain/SETUP.md

Second Brain + Obsidian MCP Setup Guide

Quick Start

1. Start Obsidian

~/.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

./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)

# Install Xvfb
sudo apt install xvfb

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

Option B: VNC/Remote Desktop

# Start a VNC server, then run Obsidian inside it

Option C: X11 Forwarding

# 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