Obsidian Sync Mcp
MCP server for Obsidian — access your vault from any AI agent, even when your machine is off. Powered by Self-hosted LiveSync.
Give any AI agent access to your Obsidian vault over MCP. Run it locally against your vault files, or pair it with Self-hosted LiveSync and deploy to the cloud so it works even when your machine is off.
Example: From your phone, ask your AI: "What's in my daily note for today?" — and get the full content back, with a link to open it in Obsidian.
How it works
The server connects to your vault in two ways:
- Filesystem mode — reads
.mdfiles directly from your vault folder. No database needed. - CouchDB mode — reads from a CouchDB database, locally or in the cloud. Your vault syncs to CouchDB via Self-hosted LiveSync, the community Obsidian plugin (600k+ downloads). The MCP server reads from CouchDB directly using livesync-commonlib — the same library that powers the plugin — for proper chunk handling and E2E encryption support.
Both modes expose the same MCP tools over HTTP, so any MCP-compatible agent can connect: Claude, Copilot, custom agents, anything that speaks the Model Context Protocol.
Choose your setup
| Need it always available? | Have LiveSync? | Go to |
|---|---|---|
| Yes | Yes | Setup A — add MCP alongside your existing CouchDB |
| Yes | No | Setup B — CouchDB + MCP + LiveSync from scratch |
| No | — | Setup C — filesystem or CouchDB, npx or Docker |
A. Deploy MCP to the cloud
You already have LiveSync and CouchDB on an always-on server. You just need the MCP server deployed alongside it.
Using Fly.io setup script (macOS/Linux, or WSL on Windows):
git clone https://github.com/es617/obsidian-sync-mcp.git
cd obsidian-sync-mcp
./deploy/setup.sh # choose option 2 (MCP only)
The script asks for your CouchDB connection details, vault name, and encryption passphrase.
Or run the Docker image on any always-on server:
docker run -p 8787:8787 \
-v mcp-data:/data -e DATA_DIR=/data \
-e COUCHDB_URL=https://your-couchdb:5984 \
-e COUCHDB_USER=admin -e COUCHDB_PASSWORD=yourpassword \
-e COUCHDB_DATABASE=obsidian -e VAULT_NAME=MyVault \
-e COUCHDB_PASSPHRASE=your-encryption-passphrase \
-e COUCHDB_OBFUSCATE_PROPERTIES=false \
-e MCP_AUTH_TOKEN=yourpassword \
-e BASE_URL=https://your-server-url \
ghcr.io/es617/obsidian-sync-mcp:latest
Set COUCHDB_PASSPHRASE if you use E2E encryption in LiveSync. Set COUCHDB_OBFUSCATE_PROPERTIES=true if "Obfuscate Properties" is also enabled in your LiveSync settings. For an existing vault the server detects the actual setting from the database at startup and corrects a mismatch with a warning; only for a brand-new empty database does the value need to match your LiveSync settings. Set BASE_URL to your public URL (required for OAuth callbacks when agents connect over HTTPS).
Your MCP endpoint is https://your-app.fly.dev/mcp (Fly.io) or https://your-server:8787/mcp (Docker behind HTTPS).
See Cost for Fly.io pricing.
Requires flyctl for the Fly.io path:
curl -L https://fly.io/install.sh | sh
export PATH="$HOME/.fly/bin:$PATH" # add to ~/.zshrc or ~/.bashrc
fly auth login
B. Deploy everything to the cloud
Starting fresh — no LiveSync yet. Deploy CouchDB and MCP together, then set up LiveSync in Obsidian.
Using Fly.io setup script (macOS/Linux, or WSL on Windows):
git clone https://github.com/es617/obsidian-sync-mcp.git
cd obsidian-sync-mcp
./deploy/setup.sh # choose option 1 (CouchDB + MCP)
The script generates credentials, creates the database, and deploys. Save the credentials it prints.
Or with Docker Compose on any always-on server:
From the project's README.