obx

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

Documentation | Quick Start | MCP Tool Reference

<p align="center"> <img src="demo.gif" alt="obx CLI demo" width="700" /> </p>

Why This Project?

| Feature | obx | Other MCP Servers | |---------|-----------------|-------------------| | No plugins required | Works directly with vault files | Often require Obsidian REST API plugin | | Single binary | One file, zero dependencies | Node.js/Python runtime needed | | Cross-platform | macOS, Linux, Windows | Often have platform issues | | 72 actions | 16 multiplexed tools, comprehensive vault operations | Typically 10-20 tools | | Fast startup | ~10ms | Seconds for interpreted languages |

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

<details> <summary>Manual download</summary>

# 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

</details>

2. Configure your MCP client:

<details> <summary><b>Claude Desktop</b></summary>

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

</details> <details> <summary><b>Claude Code</b></summary>

The server will be auto-discovered, or add to your config:

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

</details> <details> <summary><b>HTTP Streamable Transport</b></summary>

Run as an HTTP server for remote access or multi-client setups:

# 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

Then configure your MCP client to connect to http://localhost:8080/mcp.

</details> <details> <summary><b>Other MCP Clients</b></summary>

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

</details>

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:

| Platform | Binary | |----------|--------| | macOS (Apple Silicon) | obx-darwin-arm64 | | macOS (Intel) | obx-darwin-amd64 | | Linux (x64) | obx-linux-amd64 | | Linux (ARM) | obx-linux-arm64 | | Windows | obx-windows-amd64.exe |

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.

| MCP Tool Group | Description | |----------------|-------------| | manage-notes | List, read, write, rename, append, delete, or duplicate notes. | | edit-note | Perform surgical find-and-replace or precise markdown header editing. | | read-batch | Read entire blocks of multiple files or extract headers simultaneously. | | search-vault | Leverage fuzzy text search, regex, tags, headings, frontmatter queries, or date queries. | | bulk-operations | Move directories, change root tags, or mass-update frontmatter fields across many files. | | manage-folders | List, create, or recursively delete directories. | | manage-frontmatter | Set, get, or remove YAML frontmatter keys; read and write Dataview inline fields. | | manage-links | Resolve backlinks, forward-links, or ask the AI to suggest new graph connections. | | manage-tasks | Parse lists of - [ ] markdown checkboxes, toggle states, or filter by completion. | | analyze-vault | Hunt for broken links, orphan notes, stubs, and get massive mathematical token/word stats. | | manage-periodic-notes | Fetch or instantiate Daily, Weekly, Monthly, or Yearly notes automatically. | | manage-templates | Find and dynamically inject markdown blocks from your templates directory. | | manage-mocs | Auto-generate alphabetical directory indices or group unlinked notes into Maps of Content. | | manage-canvas | Create logic nodes and draw line edges across Obsidian JSON .canvas files. | | refactor-notes | Split notes by heading, merge multiple notes, or extract sections to new notes. | | manage-vaults | (Opt-in only) Dynamically remount the active server workspace without restarting. |

[!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

| Variable | Example | |----------|---------| | {{date}} | 2024-01-15 | | {{time}} | 14:30 | | {{datetime}} | 2024-01-15 14:30 | | {{year}} | 2024 | | {{month}} | 01 | | {{day}} | 15 | | {{title}} | Note title | | {{filename}} | Note.md | | {{timestamp}} | Unix timestamp |

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