Obsidian Sync MCP

黑曜石同步MCP

允许任何AI代理通过MCP访问您的黑曜石保险库。在本地针对vault文件运行它，或将其与 自托管LiveSync 并部署到云端，这样即使您的机器关闭，它也能正常工作。

例子： 从你的手机上，问你的人工智能：“我今天的日记里有什么？”——然后把全部内容拿回来，并附上用黑曜石打开的链接。

______________________________________________________________________

运作原理

服务器通过两种方式连接到您的保管库：

• 文件系统模式 --阅读 .md 直接从vault文件夹中下载文件。不需要数据库。

这两种模式都通过HTTP公开了相同的MCP工具，因此任何与MCP兼容的代理都可以连接：Claude、Copilot、自定义代理、任何能说 模型上下文协议.

______________________________________________________________________

选择您的设置

______________________________________________________________________

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 MCP_AUTH_TOKEN=yourpassword \
  -e BASE_URL=https://your-server-url \
  ghcr.io/es617/obsidian-sync-mcp:latest

集 COUCHDB_PASSPHRASE 如果您在LiveSync中使用E2E加密。集 BASE_URL 到您的公共URL（当代理通过HTTPS连接时，OAuth回调需要）。

您的MCP端点为 https://your-app.fly.dev/mcp （Fly.io）或 https://your-server:8787/mcp （HTTPS背后的Docker）。

看 成本 Fly.io定价。

需要 flyctl 对于Fly.io路径：

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  “在我的每日笔记中添加一个要点。”“找到我关于MCP服务器的笔记，并修复第二个笔记中的拼写错误。”

______________________________________________________________________

## 认证

集 `MCP_AUTH_TOKEN` 设置密码以启用身份验证：

MCP_AUTH_TOKEN=mysecretpassword npx obsidian-sync-mcp

该服务器包含一个自包含的OAuth 2.1提供程序。当代理连接时：

1. 浏览器窗口打开，显示密码页面
1. 进入 `MCP_AUTH_TOKEN` 密码
1. 代理获取访问令牌并透明地刷新它

会话在所有Claude界面（桌面、Web、移动）上共享，并在服务器重启时持续存在。在14天不活动后，您需要重新输入密码（可通过以下方式配置 `MCP_REFRESH_DAYS`).

对于非OAuth客户端（curl、MCP Inspector、自定义代理），您还可以直接将令牌传递为 `Authorization: Bearer `.

没有 `MCP_AUTH_TOKEN`，服务器无需身份验证即可运行，适合本地使用或在专用网络后面使用。

______________________________________________________________________

## 环境变量

|变量|必填|默认|描述|
|---|---|---|---|
| `VAULT_PATH` |文件系统模式|--|黑曜石保管库目录的路径|
| `COUCHDB_URL` |CouchDB模式|--|CouchDB服务器URL|
| `COUCHDB_USER` |沙发数据库模式| `admin` |CouchDB用户名|
| `COUCHDB_PASSWORD` |CouchDB模式|--|CouchDB密码（必填）|
| `COUCHDB_DATABASE` |沙发数据库模式| `obsidian` |CouchDB数据库名称|
| `COUCHDB_PASSPHRASE` |CouchDB模式|--|LiveSync E2E加密密码（必须与插件设置匹配）|
| `COUCHDB_OBFUSCATE_PROPERTIES` |沙发数据库模式| `false` |设置为 `true` 如果在LiveSync中启用了“混淆属性”（混淆数据库中的文件路径、大小、日期）|
| `VAULT_NAME` |两者皆有| `MyVault` |Vault名称（用于深度链接和索引存储）|
| `MCP_AUTH_TOKEN` |可选|--|身份验证密码|
| `BASE_URL` |可选| `http://localhost:PORT` |公共URL（用于使用隧道时的OAuth回调）|
| `PORT` |可选| `8787` |HTTP端口|
| `HOST` |可选| `0.0.0.0` |绑定地址(`127.0.0.1` 限制为本地主机）|
| `DATA_DIR` |可选| `~/.obsidian-mcp` |持久数据目录（元数据索引、身份验证令牌）|
| `LOG_LEVEL` |可选|--|设置为 `debug` 用于详细日志记录（库日志、更改提要、索引同步）|
| `MCP_REFRESH_DAYS` |可选| `14` |身份验证会话到期前几天|
| `READ_ONLY` |可选| `false` |设置为 `true` 禁用所有写入工具(`write_note`, `edit_note`, `delete_note`, `move_note`).只有读取工具通过MCP暴露。当与多个AI客户端共享服务器时很有用，应该选择加入写入权限|

集 `VAULT_PATH` 用于文件系统模式或 `COUCHDB_URL` 适用于CouchDB模式。

______________________________________________________________________

## 尝试不使用代理

使用交互方式测试服务器 [MCP检查员](https://github.com/modelcontextprotocol/inspector):

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

将运输设置为 **可流式传输的HTTP**，输入 `http://localhost:8787/mcp`，并连接。

______________________________________________________________________

## 如何更新

|如何运行它|如何更新|
|---|---|
| `npx obsidian-sync-mcp` |自动--npx拉最新|
|Fly.io |来自您运行安装程序的同一目录： `fly deploy`如果你飞丢了。汤姆，快跑 `fly config save --app your-app-name` 以恢复它|
|Docker| `docker pull ghcr.io/es617/obsidian-sync-mcp:latest` 并重新启动|

______________________________________________________________________

## 已知限制

- **每个实例一个保险库。** 每台服务器连接到一个保管库。对于多个Vault，请在不同端口上运行多个实例。
- **Fly.io上的单机。** Auth状态在内存中，因此多台机器会破坏OAuth流。安装脚本会自动执行此操作。
- **没有冲突解决方案。** 如果代理人和黑曜石同时编辑同一个音符，则最后一次写入获胜。
- **仅文本。** 二进制附件不通过MCP工具公开。
- **深度链接取决于客户端。** 黑曜石 `obsidian://` 深度链接包含在每个工具响应中。它们在Claude Mobile和浏览器中工作，但一些客户端（Claude Desktop）可能不会将它们呈现为可点击的链接。
- **需要节点22+。**
- **安装脚本需要bash。** 这 `deploy/setup.sh` 该脚本适用于macOS和Linux。在Windows上，使用WSL或Git Bash。

______________________________________________________________________

## 安全

此服务器允许AI代理对您的黑曜石保险库进行读/写访问。

**代理人可以修改和删除注释。** 保留备份。有意使用工具批准。

**身份验证是可选的。** 始终设置 `MCP_AUTH_TOKEN` 当暴露在互联网上时。

**在生产环境中使用HTTPS。** 使用隧道或部署在反向代理后面。

该软件按原样提供 [MIT许可证](https://github.com/es617/obsidian-sync-mcp/blob/main/LICENSE)你对特工如何处理你的保险库负责。

______________________________________________________________________

## 发展

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

______________________________________________________________________

## 许可证

麻省理工学院——见 [许可证](https://github.com/es617/obsidian-sync-mcp/blob/main/LICENSE).

## 致谢

- [自托管LiveSync](https://github.com/vrtmrz/obsidian-livesync) vrtmrz——黑曜石插件和CouchDB同步协议
- [livesync通用库](https://github.com/vrtmrz/livesync-commonlib) 通过vrtmrz--用于读/写LiveSync文档格式的共享库
- [FastMCP](https://github.com/punkpeye/fastmcp) --TypeScript MCP框架
- [沙发数据库](https://couchdb.apache.org/) --文档数据库
- [Fly.io](https://fly.io/) --部署平台