# obsidian-sync-mcp

Lets an AI agent read your Obsidian vault, either straight from the folder or from CouchDB synced by Self-hosted LiveSync.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 66
- Author: es617
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/es617/obsidian-sync-mcp
- Updated: 2026-10-18
- HTML: https://affpapa.org/en/nevibecode/mcp/obsidian-sync-mcp

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `VAULT_PATH`, `COUCHDB_URL`, `COUCHDB_USER`, `COUCHDB_PASSWORD`, `COUCHDB_DATABASE`, `COUCHDB_PASSPHRASE`, `COUCHDB_OBFUSCATE_PROPERTIES`, `VAULT_NAME`, `MCP_AUTH_TOKEN`, `BASE_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.
- Works with: Obsidian

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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
```
Replace <…> with your own values. 6 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
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-mcp
```
Replace <…> with your own values. 6 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-mcp
```
Replace <…> with your own values. 6 more environment variables are in the server README

## When to use it
- 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
- What's in my daily note for today?
- Find every note about MCP in my vault and link them
- Read `projects/roadmap.md` and summarize the plan

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md