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?

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

# 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:

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

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

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

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

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.

# 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:

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

Command	Description
mise run build	Build binary
mise run test	Run tests
mise run lint	Run linters
mise run check	All checks
mise run fuzz	Fuzz tests

---

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