接入你的智能体
发布者自己的命令。不是 PlugMCP 端点。
用我们的密钥与日志托管一份副本。
npx -y [email protected]Claude Code 没有针对本地命令的安装链接。复制下方命令并在终端中运行。
claude mcp add obsidian-sync-mcp -- npx -y obsidian-sync-mcp@0.11.0在终端中运行。
{ "mcpServers": { "obsidian-sync-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
远程 URL 还是本机命令？ 两种安装方式的区别
来自发布者
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.
Give any AI agent access to your Obsidian vault over MCP
The server connects to your vault in two ways:
.md files directly from your vault folder. No database needed.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.
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. If the vault was created with LiveSync 1.0.33+ and path obfuscation, also set COUCHDB_ID_DERIVATION_KEY to your LiveSync recovery code (sls-id-v1:..., from "Show current recovery code") so the server can resolve note paths. 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
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:
git clone https://github.com/es617/obsidian-sync-mcp.git
cd obsidian-sync-mcp
cat > .env <<EOF
COUCHDB_PASSWORD=changeme
MCP_AUTH_TOKEN=changeme-too
VAULT_NAME=MyVault
EOF
docker compose up -d
After deployment:
https://your-app.fly.dev/mcp (Fly.io). With Docker Compose the MCP port is published on localhost:8787 only; to reach it from other machines, put an HTTPS tunnel or reverse proxy in front (see remote access) and set BASE_URL to its public URLMCP_AUTH_TOKEN is the password you enter when an agent connectsAlways-on server
├── CouchDB + persistent storage
└── MCP server
↑ ↑
Obsidian + LiveSync AI agents
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
Applies to both Setup A and Setup B.
As of March 2026, Fly.io may waive charges under $5/month, which could make this effectively free with a shared IPv4. Either way, cheaper than Obsidian Sync ($4/month) and you own the data.
Run the MCP server locally. Works with filesystem mode (reads vault files directly) or CouchDB mode (if you have LiveSync). Machine must stay on for agents to reach it.
Filesystem mode (simplest):
VAULT_PATH=~/Documents/MyVault \
VAULT_NAME=MyVault \
npx obsidian-sync-mcp
CouchDB mode (if you have LiveSync):
COUCHDB_URL=http://localhost:5984 \
COUCHDB_USER=admin \
COUCHDB_PASSWORD=yourpassword \
COUCHDB_DATABASE=obsidian \
COUCHDB_PASSPHRASE=your-encryption-passphrase \
COUCHDB_OBFUSCATE_PROPERTIES=false \
VAULT_NAME=MyVault \
npx obsidian-sync-mcp
Omit COUCHDB_PASSPHRASE if you don't 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. If the vault was created with LiveSync 1.0.33+ and path obfuscation, also set COUCHDB_ID_DERIVATION_KEY to your LiveSync recovery code (sls-id-v1:...) so the server can resolve note paths.
Or with Docker:
docker run -p 127.0.0.1:8787:8787 \
-v mcp-data:/data -e DATA_DIR=/data \
-e VAULT_PATH=/vault -v ~/Documents/MyVault:/vault \
-e VAULT_NAME=MyVault \
ghcr.io/es617/obsidian-sync-mcp:latest
Your MCP endpoint is http://localhost:8787/mcp.
Want remote access? Add a tunnel (machine must stay on):
cloudflared tunnel --url http://localhost:8787 # free
tailscale funnel 8787 # or Tailscale
ngrok http 8787 # or ngrok
Set BASE_URL to the tunnel URL when using authentication.
Every tool response includes an Obsidian deep link (obsidian://open?vault=...&file=...) that works on Mac and iOS.
"Add a bullet point to my daily note." "Find my notes about the MCP server and fix the typo in the second one."
Set MCP_AUTH_TOKEN to a password to enable authentication:
MCP_AUTH_TOKEN=mysecretpassword npx obsidian-sync-mcp
The server includes a self-contained OAuth 2.1 provider. When an agent connects:
MCP_AUTH_TOKEN passwordThe session is shared across all your Claude interfaces (Desktop, Web, Mobile) and persists across server restarts. You'll need to re-enter the password after 14 days of inactivity (configurable via MCP_REFRESH_DAYS).
For non-OAuth clients (curl, MCP Inspector, custom agents), you can also pass the token directly as Authorization: Bearer <MCP_AUTH_TOKEN>.
Without MCP_AUTH_TOKEN, the server runs without authentication — suitable for local use or behind a private network.
Set VAULT_PATH for filesystem mode or COUCHDB_URL for CouchDB mode.
Test the server interactively using the MCP Inspector:
VAULT_PATH=~/Documents/MyVault npx obsidian-sync-mcp &
npx @modelcontextprotocol/inspector
Set transport to Streamable HTTP, enter http://localhost:8787/mcp, and connect.
obsidian:// deep links are included in every tool response. They work on Claude Mobile and in browsers, but some clients (Claude Desktop) may not render them as clickable links.deploy/setup.sh script works on macOS and Linux. On Windows, use WSL or Git Bash.This server gives an AI agent read/write access to your Obsidian vault.
Agents can modify and delete notes. Keep backups. Use tool approval deliberately.
Authentication is optional. Always set MCP_AUTH_TOKEN when exposing to the internet.
Use HTTPS in production. Use a tunnel or deploy behind a reverse proxy.
Don't leave LOG_LEVEL=debug on in production. Debug logging records every tool call's arguments, including note contents, and full error stacks. Credentials embedded in COUCHDB_URL are redacted from logs at every level.
This software is provided as-is under the MIT license. You are responsible for what agents do with your vault.
git clone --recursive https://github.com/es617/obsidian-sync-mcp.git
cd obsidian-sync-mcp
npm install && npm run build
npm test # unit tests
npm run test:e2e # integration tests
MIT — see LICENSE.
{ "mcpServers": { "obsidian-sync-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 配置。它使用发布者的安装方式，而不是 PlugMCP 代理。
此记录未列出必需的环境变量。
Obsidian Sync 通过 stdio 在本地运行。
上次检查时间：2026-11-10。 Give any AI agent access to your Obsidian vault over MCP