通过 Cloudflare 使用 Obsidian + Claude

使用 Cloudflare Workers + Containers 上的 MCP 服务器，从 Claude（网页版、桌面版、Code）访问您的 Obsidian 库。

无需 NAS，无需 Docker Compose，无需隧道。只需 Cloudflare 基础设施和用于构建标准 MCP 服务器的 Agents SDK。

架构

Obsidian (phone, desktop)
        │
        │ Obsidian Sync (your existing subscription)
        ▼
Cloudflare Container (Node.js 22)
   runs `ob sync --continuous`
   serves vault files over HTTP API
        ▲
        │ container fetch (native)
        │
Cloudflare Worker (MCP server via Agents SDK)
   tools: list, read, search, write, append, delete
   auth via bearer token (or OAuth / Cloudflare Access)
        ▲
        │ MCP over Streamable HTTP
        │
Claude (web, desktop, Code)

容器是单一事实来源。它运行 obsidian-headless 以与 Obsidian Sync 同步，并公开一个用于文件操作的 HTTP API。Worker 将所有 MCP 工具调用代理到容器的 API。

Related MCP server: obsidianMCP

MCP 工具

先决条件

• 拥有 Workers 付费计划（每月 5 美元）的 Cloudflare 账户

• 有效的 Obsidian Sync 订阅

• 工作站上安装 Node.js 22+

• wrangler CLI: npm install -g wrangler

设置

0. Wrangler 登录

wrangler login

所有必需的权限范围均默认授予。

1. 生成 Obsidian 身份验证令牌

在工作站上执行一次性步骤：

npm install -g obsidian-headless

ob login
# Enter email, password, MFA code if enabled

ob sync-list-remote
# Note your vault name

2. 配置环境

复制示例环境变量文件并填入您的值：

cp .dev.vars.example .dev.vars

使用您的 Obsidian 凭据和可选的 MCP 身份验证令牌编辑 .dev.vars。此文件供 wrangler dev 进行本地开发使用，并由设置脚本用于将密钥推送到 Cloudflare。它已包含在 .gitignore 中。

3. 部署

运行设置脚本以推送所有密钥并进行部署：

./scripts/setup.sh

或者单独运行步骤：

./scripts/setup.sh secrets         # Push secrets to Cloudflare
./scripts/setup.sh validate        # Check prerequisites
./scripts/setup.sh deploy          # Validate + install deps + deploy + restart container
./scripts/setup.sh status          # Check sync container health
./scripts/setup.sh restart         # Restart sync container
./scripts/setup.sh container-logs  # View sync container logs

您的 MCP 服务器已在以下地址上线： https://obsidian-mcp.<your-subdomain>.workers.dev/mcp

4. 连接 Claude

Claude.ai (网页版)

设置 → 连接器 → 添加自定义连接器：

• URL: https://obsidian-mcp.<your-subdomain>.workers.dev/mcp?token=YOUR_MCP_AUTH_TOKEN

• OAuth 字段留空 — URL 中的令牌负责处理身份验证

Claude Code

claude mcp add \
  --transport http \
  --scope user \
  obsidian-vault \
  https://obsidian-mcp.<your-subdomain>.workers.dev/mcp

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "obsidian-vault": {
      "url": "https://obsidian-mcp.<your-subdomain>.workers.dev/mcp"
    }
  }
}

数据流向

您在手机上编辑笔记：

1. Obsidian Sync 推送更改

2. 容器的 ob sync --continuous 将其拉取到 /vault

3. 下次 Claude 读取或搜索时，Worker 将请求代理到直接从 /vault 读取数据的容器 HTTP API

Claude 创建笔记：

1. Worker 接收 MCP write_note 调用

2. Worker 将其代理到容器的 HTTP API

3. 容器将文件写入 /vault

4. ob sync 检测到新文件并通过 Obsidian Sync 推送

5. 它会出现在您的手机和桌面上

开发

# Local dev (MCP server only, no container)
npm run dev

# Deploy
npm run deploy

成本

项目结构

obsidian-mcp/
├── src/
│   └── index.ts              # MCP server (Agents SDK, proxies to container)
├── sync-container/
│   ├── Dockerfile            # Headless sync container image
│   ├── entrypoint.sh         # Auth, sync startup
│   └── server.js             # HTTP API for vault file operations
├── scripts/
│   └── setup.sh              # Push secrets, deploy
├── .dev.vars.example         # Template for env vars / secrets
├── wrangler.jsonc            # Worker + Container config
└── package.json

后续步骤

以下内容留作练习，以根据您的需求强化设置：

身份验证强化

包含的身份验证（MCP_AUTH_TOKEN 密钥）同时支持 Authorization: Bearer 请求头和 ?token= 查询参数。URL 令牌方式对于自定义请求头不总是可用的 Claude.ai 连接器非常方便。

对于共享或公共部署，请考虑更强的选项：

• Cloudflare Access: 在 Worker 前面放置 Zero Trust Access，以实现基于身份的 SSO，并带有审计日志，无需更改代码

• OAuth: 集成 workers-oauth-provider 以实现 GitHub/Google OAuth 流程

容器身份验证

检查 obsidian-headless 是否支持用于 ob login 的 --token 或基于环境变量的身份验证，以避免交互式提示。如果不支持，请从一次性交互式登录中持久化身份验证会话，并在容器启动时恢复它。

容器重启恢复能力

ob sqlite 状态文件位于临时容器磁盘上。重启会触发完全重新同步。解决方法：在 entrypoint.sh 中添加一个 SIGTERM 陷阱以持久化状态文件，并在启动时恢复它。

搜索性能

暴力搜索会为每个查询读取每个 .md 文件 — 对于少于 500 个文件的情况尚可。对于更大的库，请在 D1 或 Workers KV 中构建搜索索引。

附件

目前仅过滤 .md 文件。通过额外工具扩展以支持图像、PDF 和其他库附件。

故障排除

Docker 必须正在运行 — 同步容器需要 Docker。运行 docker info 进行验证。validate 子命令会自动检查此项。

两个密码 — OBSIDIAN_PASSWORD 是您的 Obsidian 账户密码（用于在 obsidian.md 登录）。VAULT_PASSWORD 是在 Obsidian → Sync → Encryption 中设置的单独端到端加密密码。如果您的库不使用 E2EE，请将 VAULT_PASSWORD 留空。

部署不会重启容器 — wrangler deploy 不会重启正在运行的容器。设置脚本会自动处理此问题。如果手动部署，请使用 ./scripts/setup.sh restart 重启。

容器日志不在 wrangler tail 中 — 容器 stdout 不会通过 wrangler tail 流式传输。请改用 ./scripts/setup.sh container-logs。

组件参考