obx MCP Server

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

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