A fast, lightweight MCP server and CLI for Obsidian vaults built in Go.
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/bininstead:curl -sSL https://raw.githubusercontent.com/zach-snell/obx/main/install.sh | bash -s -- --user
Manual download
# 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:
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"obsidian": {
"command": "/path/to/obx",
"args": ["mcp", "/path/to/your/vault"]
}
}
}
Claude Code
The server will be auto-discovered, or add to your config:
{
"mcpServers": {
"obsidian": {
"command": "/path/to/obx",
"args": ["mcp", "/path/to/your/vault"]
}
}
}
HTTP Streamable Transport
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.
Other MCP Clients
# 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
pathparameters use paths likeprojects/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
Tools (1)
vault-operationsProvides access to 16 multiplexed tools for managing notes, search, templates, tasks, links, frontmatter, and vault analysis.Environment Variables
OBSIDIAN_ADDRSets the address for the HTTP server modeConfiguration
{"mcpServers": {"obsidian": {"command": "/path/to/obx", "args": ["mcp", "/path/to/your/vault"]}}}