Bumblebee
136 lines
3.5 KiB
Markdown
136 lines
3.5 KiB
Markdown
# 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
|