vault-sync
Give any MCP-compatible AI assistant full access to your Obsidian vault. Read, search, create, and edit notes through natural language. Changes sync to every device through Obsidian Sync.
vault-sync connects to the Obsidian Sync service as a headless client and exposes your vault over MCP (Model Context Protocol). Any MCP client (Claude, Cursor, Windsurf, custom agents) can work with your notes directly, and every change propagates to your phone, tablet, and desktop through the same sync service your vault already uses.
This is an unofficial, third-party client. It is not affiliated with or endorsed by Obsidian. Requires an active Obsidian Sync subscription. Use at your own risk.
Running Modes
vault-sync is a single binary with two features that can be enabled independently.
Features
- Two-way encrypted sync via WebSocket supporting encryption versions 0, 2, and 3 (AES-256-GCM + AES-SIV-CMAC, scrypt key derivation)
- Three-way merge for
.mdfiles, shallow JSON merge for.obsidian/config - Real-time file watching with debounce and offline queue
- MCP server with 8 tools: list, read, search, write, edit, delete, move, copy (docs)
- OAuth 2.1 authentication (authorization code with PKCE, client credentials for headless clients, dynamic client registration, refresh token rotation)
- Full-text search using ripgrep (with Go fallback)
- Cross-platform: Linux, macOS, Windows
Authentication
See authentication documentation for setup and usage.
Quick Start
cp .env.example .env # fill in credentials
docker compose -f docker/docker-compose.yml up -d
See the getting started guide for full setup instructions including HTTPS configuration and MCP client setup.
Configuration
All configuration via environment variables or .env file.
Sync
MCP Server
At least one of MCP_AUTH_USERS, MCP_CLIENT_CREDENTIALS, or MCP_API_KEYS is required when MCP is enabled.
Config Sync Toggles
These control which .obsidian/ files are synced. All default to false.
SYNC_MAIN_SETTINGS, SYNC_APPEARANCE, SYNC_THEMES_SNIPPETS, SYNC_HOTKEYS, SYNC_ACTIVE_CORE_PLUGINS, SYNC_CORE_PLUGIN_SETTINGS, SYNC_COMMUNITY_PLUGINS, SYNC_INSTALLED_PLUGINS
Development
Requires Go 1.27+ and just.
just build # build binary to bin/vault-sync
just test # go test -v -race ./...
just lint # golangci-lint run
just lint-fix # golangci-lint run --fix
just check # lint + test + build
just test-coverage # run tests with coverage report
just docker-build # build Docker image
just clean # remove build artifacts
Project Structure
cmd/vault-sync/ Entry point
internal/
auth/ OAuth 2.1 server
config/ Environment variable parsing
errors/ Sentinel errors
logging/ Structured logging (slog)
mcpserver/ MCP tool registration
models/ Shared types
obsidian/ Sync protocol implementation
server/ HTTP mux construction
state/ bbolt persistence
vault/ Filesystem operations for MCP
docker/ Dockerfile and docker-compose.yml
docs/ MCP tool documentation
Disclaimer
This is an unofficial, third-party client. It is not developed, maintained, or supported by the Obsidian team. The sync protocol is undocumented and may change without notice. No warranty is provided. The authors are not responsible for data loss or account issues.
License
MIT