obx

A fast, lightweight MCP server for Obsidian vaults. Built in Go for speed and simplicity.

Documentation | Quick Start | MCP Tool Reference

Why This Project?

Quick Start

1. Install with one command:

curl -sSL https://raw.githubusercontent.com/zach-snell/obx/main/install.sh | bash

This auto-detects your OS/architecture and installs to /usr/local/bin.

No sudo? Install to ~/.local/bin instead:

curl -sSL https://raw.githubusercontent.com/zach-snell/obx/main/install.sh | bash -s -- --user

# macOS (Apple Silicon)
curl -sSL https://github.com/zach-snell/obx/releases/latest/download/obx-darwin-arm64 -o obx && chmod +x obx

# macOS (Intel)
curl -sSL https://github.com/zach-snell/obx/releases/latest/download/obx-darwin-amd64 -o obx && chmod +x obx

# Linux
curl -sSL https://github.com/zach-snell/obx/releases/latest/download/obx-linux-amd64 -o obx && chmod +x obx

2. Configure your MCP client:

{
  "mcpServers": {
    "obsidian": {
      "command": "/path/to/obx",
      "args": ["mcp", "/path/to/your/vault"]
    }
  }
}

{
  "mcpServers": {
    "obsidian": {
      "command": "/path/to/obx",
      "args": ["mcp", "/path/to/your/vault"]
    }
  }
}

# Start HTTP server on port 8080
obx mcp /path/to/vault --http :8080
# or via env var
OBSIDIAN_ADDR=:8080 obx mcp /path/to/vault

# Run directly (communicates via stdio, default)
obx mcp /path/to/vault

3. Start using it! Ask your AI assistant to search your vault, create notes, manage tasks, etc.

⚠️ Paths are relative to the vault root. All path parameters use paths like projects/todo.md, not the full filesystem path. Using absolute paths will create nested directories inside your vault.

Installation Options

Pre-built Binaries (Recommended)

Download from Releases:

Go Install

go install github.com/zach-snell/obx/cmd/obx@latest
mv $(go env GOPATH)/bin/server $(go env GOPATH)/bin/obx

Build from Source

git clone https://github.com/zach-snell/obx.git
cd obx
go build -o obx ./cmd/obx

Upgrade

Just run the install script again - it always fetches the latest version:

curl -sSL https://raw.githubusercontent.com/zach-snell/obx/main/install.sh | bash

Advanced Server Configuration

obx mcp supports flags for strict access control and dynamic operations:

Selective Tool Disablement

If you don't want the AI assistant to access specific tools (e.g. bulk operations or deletion), you can blacklist entire tool groups using the --disabled-tools flag:

obx mcp /my/vault --disabled-tools manage-folders,bulk-operations,manage-frontmatter

Dynamic Vault Switching

By default, an obx mcp instance is locked to a single vault path. If you want to allow an LLM to switch the active vault dynamically via the MCP protocol without restarting the server, enable it like this:

obx mcp /my/vault --allow-vault-switching

To restrict which vaults the agent is allowed to switch to, first define aliases using setup commands like obx vault add my-notes /path/to/notes, then pass the allowed aliases to the server:

obx mcp /my/vault --allow-vault-switching --allowed-vaults my-notes,work,personal

MCP Tool Reference (16 Multiplexed)

obx multiplexes its 72 actions into 16 MCP tool groups to prevent context-window exhaustion and stay well under LLM tool limit restraints (e.g. Cursor allows 40, Copilot allows 128). You pass an "action" argument to each tool to route to the specific functionality.

[!NOTE] For the exhaustive list of action arguments accepted by each tool group, please read the Official Documentation Site.

Token-Efficient + Safe Writes

High-frequency tools now support compact responses and destructive tools support preview-first workflows.

Response Modes

• mode=compact (default): small JSON envelope with summary + bounded data
• mode=detailed: legacy markdown-rich output for human reading

Example compact envelope:

{
  "status": "ok",
  "mode": "compact",
  "summary": "Found 42 notes",
  "truncated": false,
  "data": {
    "total_count": 42,
    "returned_count": 42
  }
}

Dry Run For Destructive/Bulk Tools

Use dry_run=true to preview operations without writing:

• delete-note, delete-folder
• bulk-tag, bulk-move, bulk-set-frontmatter
• merge-notes, extract-note, extract-section
• batch-edit-note

Optimistic Concurrency

Write/edit tools accept optional expected_mtime (RFC3339Nano).
If file modification time differs, the operation fails instead of overwriting newer changes.

Usage Examples

Daily Workflow

"Create today's daily note and show me my open tasks"
"What did I work on last week?"
"Find notes I haven't touched in 3 months"

Research & Writing

"Search my vault for anything about 'machine learning'"
"Find all notes tagged #project and #active"
"What notes mention 'API design' but aren't linked?"

Vault Maintenance

"Find orphan notes with no connections"
"Show me stub notes under 100 words"
"Generate a MOC for my projects folder"

Bulk Operations

"Add #archive tag to all notes in the old-projects folder"
"Move all notes tagged #2023 to the archive folder"
"Set status: complete on these 5 project notes"

Template Variables

Create templates in your templates/ folder:

---
title: {{title}}
date: {{date}}
status: {{status:draft}}
---

# {{title}}

Created: {{datetime}}

Built-in Variables

Use {{var:default}} for default values.

Task Format

Compatible with Obsidian Tasks plugin:

- [ ] Open task
- [x] Completed task
- [ ] Has due date 📅 2024-01-15
- [ ] High priority ⏫
- [ ] Medium priority 🔼
- [ ] Low priority 🔽
- [ ] Tagged #project #urgent

Security

• Path traversal protection: All file operations are sandboxed to your vault
• Read-only by default: Write operations require explicit tool calls
• No network access: The server only accesses local files

Development

# Setup (requires Go 1.21+)
git clone https://github.com/zach-snell/obx.git
cd obx

# With mise (recommended)
mise install && mise run check

# Without mise
go build -o obx ./cmd/obx
go test -race -cover ./...
go test -bench 'Benchmark(ListNotes|SearchVault)' ./internal/vault

Available Commands

FAQ

Q: Do I need Obsidian running?
A: No. This server works directly with vault files on disk.

Q: Will this conflict with Obsidian?
A: No. Both can access the same files safely.

Q: What about sync (iCloud, Dropbox, etc)?
A: Works fine. The server reads/writes standard markdown files.

Q: Can I use multiple vaults?
A: Yes! You have two main options:

1. Run multiple server instances, each pointing to a different vault on a different port.
2. Register vaults globally via obx vault add <alias> <path> and run the server with obx mcp --allow-vault-switching --allowed-vaults <aliases...>. This exposes a manage-vaults MCP tool allowing the AI assistant to switch between them dynamically.

License

Apache 2.0 - see LICENSE