Log inSubmit server
Obsidian Sync MCP logo

Obsidian Sync MCP

Connects AI agents to an Obsidian vault for reading, searching, editing, organizing, and inspecting notes.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Obsidian Sync MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "obsidian-sync-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-sync-mcp"
      ],
      "env": {
        "VAULT_PATH": "YOUR_VALUE_HERE",
        "VAULT_NAME": "YOUR_VALUE_HERE",
        "COUCHDB_URL": "YOUR_VALUE_HERE",
        "COUCHDB_USER": "YOUR_VALUE_HERE",
        "COUCHDB_PASSWORD": "YOUR_VALUE_HERE",
        "COUCHDB_DATABASE": "YOUR_VALUE_HERE",
        "COUCHDB_PASSPHRASE": "YOUR_VALUE_HERE",
        "MCP_AUTH_TOKEN": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

npx -y obsidian-sync-mcp

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 5d ago.

Overview

The obsidian-sync-mcp MCP server gives AI agents access to an Obsidian vault through local Markdown files or a CouchDB database used by Self-hosted LiveSync. It exposes tools for reading, creating, editing, moving, deleting, listing, and inspecting notes, folders, tags, and links over an HTTP MCP endpoint. Use it locally when the vault machine is available, or deploy it with CouchDB for access while the local machine is offline.

Use cases

  • Read daily notes and return their full Markdown content
  • Find notes by folder, tag, name, or modification date
  • Update notes with targeted additions or exact-text replacements
  • Inspect backlinks and outgoing links while navigating a vault

Key features

  • Filesystem and CouchDB vault access
  • Note creation, editing, deletion, and renaming
  • Folder, tag, and note discovery
  • Frontmatter and knowledge-graph metadata
  • HTTP MCP endpoint with optional OAuth authentication
  • Obsidian deep links in tool responses

Tools10

What Obsidian Sync MCP lets your agent do. Expand a tool for its parameters.

Self-reported~257 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

7/7 checks healthy over the last 41d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 15d ago via OSV.dev · obsidian-sync-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars65Stargazers on the source repository.
npm downloads1.7kPackage downloads in the last 30 days.
Last commit5d agoMost recent push to the default branch.
Install checkInconclusiveDidn't respond in our test window — often a slow first install.
Tools exposed10Callable tools this server registers over MCP.
Directory activity5 viewsConfig copies, upvotes, and views on AllMCPs.

How Obsidian Sync MCP works

What obsidian-sync-mcp MCP server does

The obsidian-sync-mcp MCP server connects MCP-compatible agents to an Obsidian vault. It supports two storage paths: direct access to Markdown files in a vault folder, and access to a CouchDB database synchronized through the Self-hosted LiveSync Obsidian plugin.

Agents can retrieve note content, create or replace notes, make targeted edits, remove notes, and move or rename files. Discovery tools expose folder and tag inventories, while note listing supports filters for folder, name, tag, and date, with sorting by name or modification time. Metadata responses include frontmatter, tags, outgoing links, backlinks, file size, and timestamps.

How it works

In filesystem mode, the process reads .md files directly from the configured vault path. This mode does not require a database. In CouchDB mode, the process reads the synchronized vault database directly using the LiveSync common library. That path supports LiveSync chunk handling and encrypted vault data when the relevant passphrase and settings are supplied.

Both modes expose the same MCP tools through an HTTP endpoint. Tool responses include an Obsidian URI that can open the referenced note in the Obsidian application. For remote use, the server can run on an always-on host alongside CouchDB, or a locally running instance can be exposed through a tunnel. The local-machine option remains unavailable when that machine is shut down.

Setup and configuration

For a local filesystem deployment, provide VAULT_PATH and VAULT_NAME, then run the package with npx or use the provided Docker image. Docker deployments mount the vault or a data directory into the container. A local HTTP endpoint is available at port 8787 by default in the documented examples.

CouchDB deployments require the database URL, credentials, database name, and vault name. If Self-hosted LiveSync uses end-to-end encryption, configure the matching encryption passphrase. The property-obfuscation setting must also match LiveSync for a new database; existing databases are checked at startup and mismatches produce a warning. Cloud setups can use the repository's deployment script or Docker Compose, with CouchDB and the MCP process hosted together or the MCP process added beside an existing CouchDB service.

Set MCP_AUTH_TOKEN to protect a remotely reachable instance. The built-in OAuth 2.1 flow presents a password page, exchanges the token for an access token, and handles refreshes. BASE_URL is needed for OAuth callbacks when agents connect over HTTPS.

Tools and capabilities

  • Read a note's Markdown content by path.
  • Create or fully overwrite a note.
  • Append, prepend after frontmatter, or replace exact text without rewriting the whole note.
  • List folders with note counts and tags with usage counts.
  • Filter and sort note listings by supported properties.
  • Delete, move, or rename notes; destination folders are created automatically.
  • Inspect frontmatter, links, backlinks, tags, timestamps, and size.

The tool set is suitable for agents that need both knowledge retrieval and controlled vault maintenance, including daily-note updates, note organization, and link-aware navigation.

Limitations and notes

CouchDB mode depends on Self-hosted LiveSync for synchronization, while filesystem mode reads the configured folder directly. Remote access requires either an always-on deployment or a tunnel to a machine that stays running. Overwriting a note replaces its entire content, so targeted changes should use the editing tool instead. Authentication is configuration-dependent; it is enabled by setting an access token rather than being implied by every local setup.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Obsidian Sync MCP

obsidian-sync-mcp is an MCP server that connects AI agents to an Obsidian vault through local Markdown files or Self-hosted LiveSync with CouchDB. Its main tools read, write, edit, list, move, delete, and inspect notes, folders, tags, metadata, backlinks, and outgoing links.

Install it by running the package with npx, using Docker, or deploying the repository's setup scripts. Filesystem mode needs a vault path and name; CouchDB mode also needs database connection settings. Docker Compose is documented for hosting CouchDB and the MCP process together.

Yes. Filesystem mode reads Markdown files directly from the configured Obsidian vault and does not need a database. Set VAULT_PATH and VAULT_NAME, then run the server locally or in Docker with the vault mounted into the container.

Yes. Configure Cursor with the endpoint and authentication settings required by your deployment.

Set MCP_AUTH_TOKEN to enable authentication. The server provides a self-contained OAuth 2.1 flow with a password page and token refresh. For HTTPS connections, also set BASE_URL to the public URL used for OAuth callbacks.

Related MCP servers

All in Knowledge & Memory All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewObsidian Sync MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/obsidian-sync-mcp?style=directory)](https://allmcps.com/mcp/obsidian-sync-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/obsidian-sync-mcp"><img src="https://allmcps.com/api/badge/obsidian-sync-mcp?style=directory" alt="Obsidian Sync MCP on AllMCPs" /></a>