obsidian-sync-mcp

Obsidian Sync MCP

通过 MCP 让任何 AI Agent 访问你的 Obsidian 库。你可以在本地直接对库文件运行，也可以将它与 Self-hosted LiveSync 搭配并部署到云端，这样即使你的设备关机，也能正常使用。

示例： 用手机向 AI 提问：“今天的每日笔记里写了什么？”——即可获取完整内容，并附上可在 Obsidian 中打开的链接。

---

工作原理

服务通过两种方式连接到你的库：

• 文件系统模式 — 直接读取库文件夹中的 .md 文件。无需数据库。
• CouchDB 模式 — 从本地或云端的 CouchDB 数据库读取。你的库通过社区 Obsidian 插件 Self-hosted LiveSync（下载量超过 600k）同步到 CouchDB。MCP 服务使用 livesync-commonlib 直接从 CouchDB 读取数据——该库也是此插件的底层库——以正确处理分块并支持端到端加密。

两种模式都通过 HTTP 提供相同的 MCP 工具，因此任何兼容 MCP 的 Agent 都能连接：Claude、Copilot、自定义 Agent，以及任何支持 Model Context Protocol 的工具。

---

选择你的配置

是否需要始终可用？	是否已安装 LiveSync？	前往
是	是	配置 A — 在现有 CouchDB 旁添加 MCP
是	否	配置 B — 从头开始部署 CouchDB + MCP + LiveSync
否	—	配置 C — 使用文件系统或 CouchDB，通过 npx 或 Docker 运行

---

A. 将 MCP 部署到云端

你已经在一台始终运行的服务器上部署了 LiveSync 和 CouchDB。现在只需在同一服务器上部署 MCP 服务。

使用 Fly.io 设置脚本（macOS/Linux，或 Windows 上的 WSL）：

git clone https://github.com/es617/obsidian-sync-mcp.git
cd obsidian-sync-mcp
./deploy/setup.sh    # choose option 2 (MCP only)

脚本会询问 CouchDB 连接信息、库名称和加密密码。

或者，在任何始终运行的服务器上运行 Docker 镜像：

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

如果在 LiveSync 中使用端到端加密，请设置 COUCHDB_PASSPHRASE。如果 LiveSync 设置中也启用了“混淆属性”，请设置 COUCHDB_OBFUSCATE_PROPERTIES=true。对于现有库，服务会在启动时从数据库检测实际设置，并在发现不匹配时发出警告并修正；只有全新的空数据库才需要确保该值与 LiveSync 设置一致。如果库是在 LiveSync 1.0.33+ 中使用路径混淆创建的，还需将 COUCHDB_ID_DERIVATION_KEY 设置为 LiveSync 恢复码（sls-id-v1:...，可通过“显示当前恢复码”获取），这样服务才能解析笔记路径。请将 BASE_URL 设置为你的公开 URL（Agent 通过 HTTPS 连接时，OAuth 回调必需此项）。

你的 MCP 端点为 https://your-app.fly.dev/mcp（Fly.io）或 https://your-server:8787/mcp（经 HTTPS 访问的 Docker 服务）。

Fly.io 定价请参见费用。

Fly.io 部署需要安装 flyctl：

curl -L https://fly.io/install.sh | sh
export PATH="$HOME/.fly/bin:$PATH"  # add to ~/.zshrc or ~/.bashrc
fly auth login

---

B. 将所有内容部署到云端

从头开始——尚未设置 LiveSync。部署 CouchDB 和 MCP，然后在 Obsidian 中设置 LiveSync。

使用 Fly.io 设置脚本（macOS/Linux，或 Windows 上的 WSL）：

git clone https://github.com/es617/obsidian-sync-mcp.git
cd obsidian-sync-mcp
./deploy/setup.sh    # choose option 1 (CouchDB + MCP)

该脚本会生成凭据、创建数据库并进行部署。请保存它输出的凭据。

或者，在任何始终运行的服务器上使用 Docker Compose：

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

部署后：

1. 在 Obsidian 中安装 Self-hosted LiveSync，并使用设置输出中的凭据进行配置
2. 你的 MCP 端点为 https://your-app.fly.dev/mcp（Fly.io）。使用 Docker Compose 时，MCP 端口仅发布在 localhost:8787；若要从其他设备访问，请在前面配置 HTTPS 隧道或反向代理（参见远程访问），并将 BASE_URL 设置为其公共 URL
3. MCP_AUTH_TOKEN 是 Agent 连接时要输入的密码

Always-on server
├── CouchDB + persistent storage
└── MCP server
      ↑                    ↑
Obsidian + LiveSync    AI agents

Fly.io 部署方式需要 flyctl：

curl -L https://fly.io/install.sh | sh
export PATH="$HOME/.fly/bin:$PATH"  # add to ~/.zshrc or ~/.bashrc
fly auth login

---

费用（Fly.io）

适用于设置 A 和设置 B。

组件	费用
CouchDB + MCP VM（共享，512MB）	~$3-4/月（LiveSync 会让它保持运行）
仅运行 MCP 的 VM（共享，256MB）	~$0-2/月（闲置时会暂停）
1GB 持久卷	~$0.15/月

截至 2026 年 3 月，Fly.io 可能免除低于 $5/月的费用，如果使用共享 IPv4，这可能让服务实际上免费。无论如何，这都比 Obsidian Sync（$4/月）便宜，而且数据由你掌控。

---

C. 在你的设备上运行

在本地运行 MCP 服务。支持文件系统模式（直接读取 vault 文件）或 CouchDB 模式（如果你使用 LiveSync）。设备必须保持运行，Agent 才能访问。

文件系统模式（最简单）：

VAULT_PATH=~/Documents/MyVault \
VAULT_NAME=MyVault \
npx obsidian-sync-mcp

CouchDB 模式（如果你使用 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

如果你在 LiveSync 中未使用 E2E 加密，请省略 COUCHDB_PASSPHRASE。如果 LiveSync 设置中也启用了“Obfuscate Properties”，请设置 COUCHDB_OBFUSCATE_PROPERTIES=true。对于现有 vault，服务会在启动时从数据库检测实际设置，并在不匹配时发出警告并进行修正；只有全新的空数据库才需要让此值与 LiveSync 设置一致。如果 vault 是使用 LiveSync 1.0.33+ 和路径混淆创建的，还需将 COUCHDB_ID_DERIVATION_KEY 设置为你的 LiveSync 恢复代码（sls-id-v1:...），以便服务解析笔记路径。

或者，使用 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

你的 MCP 端点为 http://localhost:8787/mcp。

需要远程访问？ 添加隧道（设备必须保持运行）：

cloudflared tunnel --url http://localhost:8787    # free
tailscale funnel 8787                             # or Tailscale
ngrok http 8787                                   # or ngrok

使用身份验证时，将 BASE_URL 设置为隧道 URL。

---

工具

工具	描述
read_note	按路径读取笔记的 Markdown 内容
write_note	创建或覆盖笔记（替换全部内容）
edit_note	编辑笔记而不重写 — 可追加、前置（在 frontmatter 后）或替换精确文本
list_folders	列出库中的所有文件夹及笔记数量 — 用于查找文件夹名称
list_tags	列出库中的所有标签及数量 — 用于筛选前查找标签
list_notes	列出笔记及时间戳。可按文件夹、名称、标签或日期筛选。按名称或修改时间排序。
search_notes	搜索笔记文本中的词语（OR，不区分大小写的子字符串）；优先搜索路径和 frontmatter 标题。可按文件夹、标签或日期筛选。在一行状态信息（说明索引已追上哪个 CouchDB 序列）之后，返回路径及各一行上下文，绝不返回笔记正文。
delete_note	删除笔记
move_note	移动或重命名笔记 — 可跨文件夹操作，并自动创建目标文件夹
get_note_metadata	获取 frontmatter、标签、外链、反向链接、大小和时间戳 — 用于浏览知识图谱

每个工具响应都包含一个 Obsidian 深层链接（obsidian://open?vault=...&file=...），可在 Mac 和 iOS 上使用。

“在我的每日笔记中添加一个项目符号。”“查找我关于 MCP 服务的笔记，并修正第二篇中的错别字。”

---

身份验证

将 MCP_AUTH_TOKEN 设置为密码以启用身份验证：

MCP_AUTH_TOKEN=mysecretpassword npx obsidian-sync-mcp

服务内置了一个独立的 OAuth 2.1 提供方。当 Agent 连接时：

1. 浏览器窗口会打开一个密码页面
2. 输入 MCP_AUTH_TOKEN 密码
3. Agent 会获取访问令牌，并自动刷新令牌

会话在你的所有 Claude 界面（桌面、Web、移动端）之间共享，并在服务重启后继续保留。闲置 14 天后，你需要重新输入密码（可通过 MCP_REFRESH_DAYS 配置）。

对于非 OAuth 客户端（curl、MCP Inspector、自定义 Agent），你也可以直接通过 Authorization: Bearer <MCP_AUTH_TOKEN> 传递令牌。

如果未设置 MCP_AUTH_TOKEN，服务将不启用身份验证 — 适用于本地使用或在专用网络后运行。

---

环境变量

变量	必需条件	默认值	描述
VAULT_PATH	文件系统模式	—	Obsidian 保管库目录的路径
COUCHDB_URL	CouchDB 模式	—	CouchDB 服务 URL
COUCHDB_USER	CouchDB 模式	admin	CouchDB 用户名
COUCHDB_PASSWORD	CouchDB 模式	—	CouchDB 密码（必需）
COUCHDB_DATABASE	CouchDB 模式	obsidian	CouchDB 数据库名称。服务不会创建数据库：如果数据库不存在，启动将报错失败
COUCHDB_PASSPHRASE	CouchDB 模式	—	LiveSync 端到端加密密码短语（必须与插件设置一致）
COUCHDB_OBFUSCATE_PROPERTIES	CouchDB 模式	false	如果 LiveSync 中启用了“Obfuscate Properties”，请设为 true（对数据库中的文件路径、大小和日期进行混淆）。对于已有保管库，实际设置会在启动时自动检测；此值仅决定全新空数据库使用的格式
COUCHDB_ID_DERIVATION_KEY	CouchDB 模式	—	LiveSync“independent ID derivation”恢复码（sls-id-v1:...）。若要读取和写入使用路径混淆、由 LiveSync 1.0.33+ 创建的保管库中的笔记，则需要此项；对于较旧的（基于密码短语派生的）保管库，请留空。可在 LiveSync 的“Show current recovery code”中获取
COUCHDB_CASE_SENSITIVE	CouchDB 模式	false	仅当 LiveSync 保管库启用了“Handle filenames as case-sensitive”时才设为 true。此设置必须与保管库一致，否则混淆后的文档 ID 将无法解析（服务会因明确的错误消息而无法启动）。其他情况请留空
VAULT_NAME	两种模式	MyVault	保管库名称（用于深层链接和索引存储）
MCP_AUTH_TOKEN	可选	—	用于身份验证的密码
BASE_URL	可选	http://localhost:PORT	公共 URL（使用隧道时用于 OAuth 回调）
PORT	可选	8787	HTTP 端口
HOST	可选	0.0.0.0	绑定地址（设为 127.0.0.1 可限制为仅本地主机）
MCP_ALLOWED_HOSTS	可选	—	以逗号分隔的额外 Host 值列表，这些值会在无身份验证模式下被接受（例如 192.168.1.5,mybox.local）。无身份验证模式会拒绝其他所有 Host，以防止浏览器 DNS 重绑定；始终允许 localhost。设置了 MCP_AUTH_TOKEN 时会忽略此项。
DATA_DIR	可选	~/.obsidian-mcp	持久化数据目录（元数据索引、身份验证令牌）
LOG_LEVEL	可选	—	设为 debug 可启用详细日志（库日志、变更 Feed、索引同步）
DISPLAY_TIMEZONE	可选	服务所在时区	用于 search_notes 状态行中服务时间可读部分的 IANA 时区（旁边始终会显示 UTC），例如 Europe/Berlin。无效时区会在启动时发出警告并回退到 UTC
MCP_REFRESH_DAYS	可选	14	身份验证会话过期前的天数
READ_ONLY	可选	false	设为 true 可禁用所有写入工具（write_note、edit_note、delete_note、move_note）。MCP 仅会公开读取工具，保管库后端也会拒绝写入。适用于与多个 AI 客户端共享服务，且写入权限应采用显式启用的场景。此设置可保护保管库不受 MCP 客户端影响；但不构成数据库级别的保证。若要让 CouchDB 本身拒绝写入，请使用 CouchDB 侧的控制措施，例如 validate_doc_update 函数，拒绝服务使用的 CouchDB 用户。
WRITE_FOLDERS	可选	—	以逗号分隔的保管库相对文件夹列表，仅允许在这些文件夹中写入（例如 MCP,Inbox）。设置后，整个保管库仍可读取，但 write_note、edit_note、delete_note 和 move_note 会拒绝操作这些文件夹之外的路径（move_note 要求源路径和目标路径均可写）。此项由服务端强制执行，不同于 MCP_INSTRUCTIONS。匹配区分大小写，并识别文件夹边界（MCP 匹配 MCP/note.md，但不匹配 MCP-private/note.md）。设置 READ_ONLY=true 时会忽略此项；未设置时，整个保管库均可写。
MCP_INSTRUCTIONS	可选	—	追加到服务的 MCP instructions 中的额外文本（客户端会将此字符串注入系统提示词）。可用它将保管库特定约定写入服务，例如文件夹结构、命名规则、应避免的文件夹等，这样所有 MCP 客户端都会应用这些约定，无需逐个客户端配置。尽力而为：并非所有客户端都会遵循 instructions。
MCP_INSTRUCTIONS_FILE	可选	—	文件路径（例如 Markdown 文件），其内容会追加到 MCP instructions 中。对于多行约定，此方式比 MCP_INSTRUCTIONS 更方便。如果两者均已设置，则以该文件为准，并忽略 MCP_INSTRUCTIONS（同时在启动时发出警告）。文件不存在、无法读取或大小超过 32 KB，都会导致启动失败。请将此文件存放在仅服务用户可写的位置（例如 chmod 600）——其内容会进入每个 MCP 会话的系统提示词，因此对该文件的写入权限等同于对每个客户端的提示词注入权限。
为文件系统模式设置 VAULT_PATH，或为 CouchDB 模式设置 COUCHDB_URL。

---

不使用 Agent 试用

使用 MCP Inspector 交互式测试服务：

VAULT_PATH=~/Documents/MyVault npx obsidian-sync-mcp &
npx @modelcontextprotocol/inspector

将传输方式设为 Streamable HTTP，输入 http://localhost:8787/mcp，然后连接。

---

如何更新

运行方式	更新方法
npx obsidian-sync-mcp	自动更新 — npx 会拉取最新版本
Fly.io	在运行设置脚本的同一目录中运行：fly deploy。如果丢失了 fly.toml，请运行 fly config save --app your-app-name 将其恢复。
Docker	运行 docker pull ghcr.io/es617/obsidian-sync-mcp:latest 并重启。镜像以非特权 node 用户（uid 1000）运行。如果数据卷由以 root 身份运行的旧镜像创建，请执行一次以下命令，使其可写：docker run --rm -v mcp-data:/data alpine chown -R 1000:1000 /data（对于绑定挂载，请对主机目录运行 chown -R 1000:1000）

---

已知限制

• 每个实例只能连接一个库。 每个服务仅连接一个库。如需连接多个库，请在不同端口运行多个实例。
• Fly.io 上只能运行一台机器。 身份验证状态存储在内存中，因此多台机器会导致 OAuth 流程失效。设置脚本会自动强制执行此限制。
• 不支持冲突解决。 如果 Agent 和 Obsidian 同时编辑同一条笔记，以最后一次写入为准。
• 仅支持文本。 二进制附件不会通过 MCP 工具公开。
• 深层链接取决于客户端。 每个工具响应都包含 Obsidian obsidian:// 深层链接。这些链接可在 Claude Mobile 和浏览器中使用，但某些客户端（如 Claude Desktop）可能无法将其呈现为可点击链接。
• 需要 Node 22+。
• 设置脚本需要 bash。 deploy/setup.sh 脚本适用于 macOS 和 Linux。在 Windows 上，请使用 WSL 或 Git Bash。

---

安全

此服务会授予 AI Agent 对 Obsidian 库的读写权限。

Agent 可以修改和删除笔记。 请保留备份，并谨慎批准工具调用。

身份验证是可选的。 向互联网公开服务时，务必设置 MCP_AUTH_TOKEN。

在生产环境中使用 HTTPS。 请使用隧道，或通过反向代理部署。

不要在生产环境中启用 LOG_LEVEL=debug。 调试日志会记录每次工具调用的参数，包括笔记内容和完整错误堆栈。日志的所有级别都会对 COUCHDB_URL 中嵌入的凭据进行脱敏。

本软件按原样提供，并遵循 MIT 许可证。对于 Agent 如何操作你的库，你需自行负责。

---

开发

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 — 详见 LICENSE。

致谢

• Self-hosted LiveSync，由 vrtmrz 开发 — Obsidian 插件和 CouchDB 同步协议
• livesync-commonlib，由 vrtmrz 开发 — 用于读写 LiveSync 文档格式的共享库
• FastMCP — TypeScript MCP 框架
• CouchDB — 文档数据库
• Fly.io — 部署平台