1. Conduid
  2. Productivity
  3. Vault Sync
MCP server · Productivity

Vault Sync

by · github.com/alexjbarnes/vault-sync

Headless Obsidian Sync client with MCP server for AI assistants

Unclaimed MIT productivity
InstallView source
59Fair

Scored 7 hours ago · breakdown

About Vault Sync

Vault Sync is an MCP server published by alexjbarnes in the Productivity category: headless Obsidian Sync client with MCP server for AI assistants.

The repository has 17 stars and 5 forks, with the last commit 3 months ago. Recent commit activity is the strongest signal that reported issues will get attention.

Install

From source
git clone https://github.com/alexjbarnes/vault-sync

This server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.

Ask AI

✦

Ask AI about Vault Sync

Powered by Claude · Grounded in docs

I know everything about Vault Sync. Ask me about installation, configuration, usage, or troubleshooting.

Security checks

Static checks derived from the repository 7 hours ago. Heuristics on the source, not an audit.

  • ✓README presentThe repository ships documentation.
  • ✓License declaredUsable under a stated license.
  • ✓Tests presentA test suite exists in the repository.
  • ✓Dependencies pinnedA lockfile pins dependency versions.
  • ✓No dynamic code executionSource scan found no eval, dynamic Function, or shell execution.
  • !Scoped permissionsDoesn't declare a permission scope. Assume it can do anything its process can.

Releases

v1.3.0v1.3.0 · 28 Mar 2026Changed Migrated OAuth/PKCE authentication from internal implementation to external `mcp-auth` v0.2.0 library Simplified `MuxConfig` from four fields to two (`Auth` and `MCPHandler`), with all OAuth endpoint registration handled by the…
v1.2.0v1.2.0 · 1 Mar 2026Added Encryption version 2 and 3 support, fixing "Wrong vault key" for vaults using newer encryption `Cipher` interface abstracting encryption version differences, with `CipherV3` implementation using AES-SIV-CMAC (RFC 5297) for path…
v1.1.0v1.1.0 · 21 Feb 2026Added OAuth `client_credentials` grant for headless MCP clients (`MCP_CLIENT_CREDENTIALS`) API key authentication (`MCP_API_KEYS`) with `vs_` prefix format Dynamic client registration (RFC 7591) with `authorization_code` and…
v1.0.0v1.0.0 · 18 Feb 2026Added Two-way encrypted sync via WebSocket (AES-256-GCM, scrypt key derivation) Three-way merge for markdown files, shallow JSON merge for config files Real-time file watching with debounce and offline queue MCP server with 8 tools:…

README

vault-sync

CI Go Coverage

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.

ENABLE_SYNC ENABLE_MCP Use case
true false Headless sync daemon. Keep a server or NAS in sync without running the desktop app.
false true MCP server only. Serve a vault directory that already exists on disk.
true true Full pipeline. Sync from Obsidian servers and serve to Claude in one process.

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 .md files, 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

Method Status Use case
OAuth 2.1 (authorization code + PKCE) Supported Interactive login from browser-based MCP clients
OAuth 2.1 (client credentials) Supported Headless agents and CI/CD pipelines
API key Supported Single static token for simple deployments

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

Variable Required Description
OBSIDIAN_EMAIL Yes Account email
OBSIDIAN_PASSWORD Yes Account password
OBSIDIAN_VAULT_PASSWORD Yes Vault encryption password
OBSIDIAN_VAULT_NAME No Vault name (auto-detected if only one exists)
OBSIDIAN_SYNC_DIR No Local directory for vault files (defaults to ~/.vault-sync/vaults/<id>/)
DEVICE_NAME No Device name reported to sync server (default: system hostname, falls back to vault-sync)
ENABLE_SYNC No Enable sync (default: true)

MCP Server

Variable Required Description
ENABLE_MCP No Enable MCP server (default: false)
MCP_SERVER_URL When MCP enabled Base URL without /mcp (e.g. https://vault.example.com). MCP clients connect to MCP_SERVER_URL/mcp.
MCP_AUTH_USERS Conditional Comma-separated user:password pairs for the OAuth login page
MCP_CLIENT_CREDENTIALS No Comma-separated client_id:secret pairs for headless OAuth clients (docs)
MCP_API_KEYS No Comma-separated user:key pairs for API key auth. Generate keys with echo "vs_$(openssl rand -hex 32)" (docs)
MCP_LISTEN_ADDR No Listen address (default: :8090)
MCP_LOG_LEVEL No Log level: debug, info, warn, error (default: info)
ENVIRONMENT No production for JSON logs, any other value for text logs (default: development)

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.25+ 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

README fetched from the repository 7 hours ago. The original is authoritative.

Questions

About Vault Sync

How do I install Vault Sync?

No package has been published for this server, so install it from source: clone the repository and follow its README.

Is Vault Sync safe to use with an AI agent?

Its trust score is 59 out of 100 (fair). It passes 5 of the 6 static security checks run so far; the failures are listed above. It has no ConduID identity yet, so agent calls to it are not receipted.

Is Vault Sync still maintained?

Yes — the last commit was 3 months ago. The repository has 17 stars and 5 forks and 3 open issues.