FAQ

General

What is obx?

obx is a powerful CLI and MCP (Model Context Protocol) server that lets AI assistants interact with your Obsidian vault. It provides 16 unified tools (multiplexing 72 distinct actions) for reading, writing, searching, and organizing notes.

Do I need Obsidian installed?

No. obx works directly with Markdown files in your vault folder. Obsidian doesn’t need to be installed or running.

Which AI assistants work with this?

Any MCP-compatible client:

• Claude Desktop
• Cursor
• Cline (VS Code extension)
• Other MCP clients

Is my data sent to the cloud?

obx itself is completely local. However, when you use it with an AI assistant like Claude, the note content you discuss is sent to that AI provider. See Security for details.

Installation

How do I install on Windows?

Download the Windows binary from GitHub Releases and add it to your PATH, or use:

go install github.com/zach-snell/obx@latest

The install script says “permission denied”

Try installing to your home directory:

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

This installs to ~/.local/bin instead of requiring sudo.

How do I upgrade?

Re-run the install script or:

go install github.com/zach-snell/obx@latest

Configuration

Where is the Claude Desktop config file?

Platform	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Can I use multiple vaults?

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 configure the MCP server with --allow-vault-switching --allowed-vaults <aliases...>. This exposes a manage-vaults MCP tool allowing the AI assistant to switch between them dynamically.

The server isn’t connecting

1. Check the path in your config is correct
2. Ensure the binary is in your PATH
3. Restart Claude Desktop completely
4. Check Claude Desktop logs for errors

Usage

How do I see all available tools?

Ask your AI assistant:

“What tools are available for my Obsidian vault?”

Or check the Tools Overview.

Why isn’t the AI finding my note?

Common causes:

• Path might be different than expected (use manage-notes action: "list")
• Search is case-insensitive but might miss partial matches
• Note might be in a subdirectory

Try:

“List all notes in my vault” or “Search for [partial name]“

Can I undo changes?

obx doesn’t have undo. Use:

• Git for version control
• Obsidian’s file recovery plugin
• Regular backups

How do I prevent accidental deletions?

Ask the AI to preview first:

“Show me what would be deleted, but don’t delete yet”

Or use find-* tools before bulk-* operations.

Features

Does it support Dataview queries?

obx can read and write Dataview inline fields (key:: value), but it doesn’t execute Dataview queries. The AI can help you query your data using the search and frontmatter tools.

Does it work with Obsidian plugins?

It works with plugin data that’s stored in files:

• Templates: Works with any template files
• Daily Notes: Works with any periodic notes
• Canvas: Full canvas support

It doesn’t interact with:

• Plugin settings
• Plugin APIs
• Obsidian’s internal state

Can it read images or PDFs?

No. obx only handles text files (Markdown, JSON for canvas). Images and PDFs are not processed.

Does it support wiki-style links?

Yes! obx fully supports [[wikilinks]] and [[wikilinks|with aliases]]. Tools like manage-links (backlinks, forward-links) and manage-notes (rename) understand and update wikilinks.

Troubleshooting

”Command not found: obx”

The binary isn’t in your PATH. Either:

• Add the install location to PATH
• Use the full path in your MCP config

”Permission denied” when accessing vault

Check file permissions:

ls -la /path/to/vault

The user running the MCP client needs read/write access.

Operations are slow

For large vaults (10,000+ notes), some operations like full-vault search may take longer. Use:

• directory parameter to limit scope
• limit parameter to cap results

Claude says it can’t access the vault

1. Restart Claude Desktop
2. Check config JSON is valid
3. Verify path exists and is accessible
4. Check Claude Desktop developer tools for errors

Comparison

vs. Obsidian REST Plugin

Feature	obx	REST Plugin
Requires Obsidian	No	Yes
Runtime	Single binary	Obsidian running
Protocol	MCP (stdio + HTTP Streamable)	HTTP REST
Tool count	16 unified (72 actions)	Varies

vs. Other MCP Servers

Feature	obx	Node.js servers
Runtime	None (binary)	Node.js
Startup	~10ms	Seconds
Install	One file	npm install
Platforms	All	Varies

Contributing

How do I report a bug?

Open an issue on GitHub with:

• What you expected
• What happened
• Steps to reproduce
• obx version

How do I request a feature?

Open a GitHub issue with the enhancement label describing:

• What you want to do
• Why it would be useful
• Any implementation ideas

Can I contribute code?

Yes! See the Development guide for setup instructions and contribution guidelines.