obsidian-sync-mcp — Claude Code MCP server for Obsidian vaults
Lets an AI agent read your Obsidian vault, either straight from the folder or from CouchDB synced by Self-hosted LiveSync.
claude mcp add --env VAULT_PATH=<VAULT_PATH> --env COUCHDB_URL=<COUCHDB_URL> --env COUCHDB_USER=<COUCHDB_USER> --env COUCHDB_PASSWORD=<COUCHDB_PASSWORD> --env COUCHDB_DATABASE=<COUCHDB_DATABASE> --transport stdio obsidian-sync-mcp -- npx -y obsidian-sync-mcpWhat obsidian-sync-mcp does
The server reaches a vault in two ways. Filesystem mode reads .md files from the vault folder and needs no database. CouchDB mode pulls notes from a database, local or hosted, that Self-hosted LiveSync keeps in sync. Chunk handling and end-to-end encryption come from livesync-commonlib, the same library behind the plugin.
Either mode publishes the same set of tools, and any client that speaks Model Context Protocol can attach. Local runs start with npx obsidian-sync-mcp: set VAULT_PATH and VAULT_NAME for filesystem mode, or COUCHDB_URL, COUCHDB_USER, COUCHDB_PASSWORD and COUCHDB_DATABASE for CouchDB. Your machine has to stay on, or the agent has nothing to talk to.
For round-the-clock access, deploy the server next to CouchDB on an always-on host, using the Fly.io script or Docker. Encrypted vaults need COUCHDB_PASSPHRASE; if “Obfuscate Properties” is on, also set COUCHDB_OBFUSCATE_PROPERTIES=true. A vault created with LiveSync 1.0.33+ and path obfuscation additionally requires COUCHDB_ID_DERIVATION_KEY set to your recovery code (sls-id-v1:...) — without it the server cannot resolve note paths.
What it helps with
- pull today's daily note out of the vault
- search the whole vault and return links to matching notes
- let an agent read notes without opening Obsidian
- reach the vault from a phone while the laptop is off
- connect an encrypted CouchDB vault to an agent
Example prompts for the agent
- What's in my daily note for today?
- Find every note about MCP in my vault and link them
- Read
projects/roadmap.mdand summarize the plan
How to install obsidian-sync-mcp
Platform CLI
claude mcp add --env VAULT_PATH=<VAULT_PATH> --env COUCHDB_URL=<COUCHDB_URL> --env COUCHDB_USER=<COUCHDB_USER> --env COUCHDB_PASSWORD=<COUCHDB_PASSWORD> --env COUCHDB_DATABASE=<COUCHDB_DATABASE> --transport stdio obsidian-sync-mcp -- npx -y obsidian-sync-mcpReplace <…> with your own values. 6 more environment variables are in the server README
Platform CLI
codex mcp add obsidian-sync-mcp --env VAULT_PATH=<VAULT_PATH> --env COUCHDB_URL=<COUCHDB_URL> --env COUCHDB_USER=<COUCHDB_USER> --env COUCHDB_PASSWORD=<COUCHDB_PASSWORD> --env COUCHDB_DATABASE=<COUCHDB_DATABASE> -- npx -y obsidian-sync-mcpReplace <…> with your own values. 6 more environment variables are in the server README
Config file
{
"mcpServers": {
"obsidian-sync-mcp": {
"command": "npx",
"args": [
"-y",
"obsidian-sync-mcp"
],
"env": {
"VAULT_PATH": "<VAULT_PATH>",
"COUCHDB_URL": "<COUCHDB_URL>",
"COUCHDB_USER": "<COUCHDB_USER>",
"COUCHDB_PASSWORD": "<COUCHDB_PASSWORD>",
"COUCHDB_DATABASE": "<COUCHDB_DATABASE>"
}
}
}
}Replace <…> with your own values. 6 more environment variables are in the server README
Config file
{
"servers": {
"obsidian-sync-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"obsidian-sync-mcp"
],
"env": {
"VAULT_PATH": "<VAULT_PATH>",
"COUCHDB_URL": "<COUCHDB_URL>",
"COUCHDB_USER": "<COUCHDB_USER>",
"COUCHDB_PASSWORD": "<COUCHDB_PASSWORD>",
"COUCHDB_DATABASE": "<COUCHDB_DATABASE>"
}
}
}
}Replace <…> with your own values. 6 more environment variables are in the server README
Platform CLI
gemini mcp add -e VAULT_PATH=<VAULT_PATH> -e COUCHDB_URL=<COUCHDB_URL> -e COUCHDB_USER=<COUCHDB_USER> -e COUCHDB_PASSWORD=<COUCHDB_PASSWORD> -e COUCHDB_DATABASE=<COUCHDB_DATABASE> obsidian-sync-mcp npx -y obsidian-sync-mcpReplace <…> with your own values. 6 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about obsidian-sync-mcp
How do I install obsidian-sync-mcp in Claude Code?
Run `claude mcp add obsidian-sync-mcp -e COUCHDB_PASSWORD=<COUCHDB_PASSWORD> -e COUCHDB_PASSPHRASE=<COUCHDB_PASSPHRASE> -e MCP_AUTH_TOKEN=<MCP_AUTH_TOKEN> -- npx -y obsidian-sync-mcp. For filesystem mode use the other form: claude mcp add --env VAULT_PATH=<VAULT_PATH> --env COUCHDB_URL=<COUCHDB_URL> --env COUCHDB_USER=<COUCHDB_USER> --env COUCHDB_PASSWORD=<COUCHDB_PASSWORD> --env COUCHDB_DATABASE=<COUCHDB_DATABASE> --transport stdio obsidian-sync-mcp -- npx -y obsidian-sync-mcp`.
What does obsidian-sync-mcp do?
It exposes your Obsidian vault to an agent over Model Context Protocol. Notes come either from vault files or from a CouchDB database kept in sync by Self-hosted LiveSync.
What do I need for CouchDB mode?
The database URL, user, password and database name. Add COUCHDB_PASSPHRASE when LiveSync uses encryption, and COUCHDB_ID_DERIVATION_KEY with your recovery code for a vault with path obfuscation.
