Obsidian Vault MCP Server
通过 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: obsidian-mcp
MCP 工具
工具 | 描述 |
| 列出所有带有路径、大小和日期的 Markdown 笔记 |
| 按路径读取笔记的全部内容 |
| 在所有笔记中进行全文搜索并显示片段 |
| 创建或覆盖笔记 |
| 追加到现有笔记(或创建它) |
| 删除笔记 |
| 创建文件夹(包含中间目录) |
| 删除文件夹(空文件夹或递归删除) |
| 列出路径下的直接子文件夹 |
先决条件
拥有 Workers 付费计划(每月 5 美元)的 Cloudflare 账户
有效的 Obsidian Sync 订阅
工作站上安装 Node.js 22+
wranglerCLI: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 name2. 配置环境
复制示例环境变量文件并填入您的值:
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_TOKENOAuth 字段留空 — URL 中的令牌负责处理身份验证
Claude Code
claude mcp add \
--transport http \
--scope user \
obsidian-vault \
https://obsidian-mcp.<your-subdomain>.workers.dev/mcpClaude Desktop
添加到 claude_desktop_config.json:
{
"mcpServers": {
"obsidian-vault": {
"url": "https://obsidian-mcp.<your-subdomain>.workers.dev/mcp"
}
}
}数据流向
您在手机上编辑笔记:
Obsidian Sync 推送更改
容器的
ob sync --continuous将其拉取到/vault下次 Claude 读取或搜索时,Worker 将请求代理到直接从
/vault读取数据的容器 HTTP API
Claude 创建笔记:
Worker 接收 MCP
write_note调用Worker 将其代理到容器的 HTTP API
容器将文件写入
/vaultob sync检测到新文件并通过 Obsidian Sync 推送它会出现在您的手机和桌面上
开发
# Local dev (MCP server only, no container)
npm run dev
# Deploy
npm run deploy成本
服务 | 用途 | 成本 |
Workers 付费计划 | 已支付 | 每月 5 美元(涵盖所有内容) |
容器 | 1 个实例,大部分时间空闲 | 包含在 Workers 计划中 |
额外总计 | $0 |
项目结构
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。
组件参考
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Notes and memory assistant: one Markdown vault that Claude, ChatGPT and any MCP client can share.
Remote streamable-HTTP MCP server running on a single Cloudflare Worker. Your assistant gets live Airbnb, Amazon, Booking.com, Google Flights, Maps and Reddit data, social search on X, Instagram and TikTok, the Meta Ad Library, and image/video generation without any keys. Connect your own accounts to let it send WhatsApp or Telegram messages, work an IMAP inbox, manage Meta Ads campaigns and publish to X and LinkedIn. OAuth 2.1 with PKCE; stored credentials are AES-256-GCM encrypted.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Related MCP Servers
- AlicenseAqualityDmaintenanceThis MCP server enables Claude to interact with an Obsidian vault for persistent, structured memory, providing tools for note creation, semantic search, graph traversal, and session memory.1826 npm15MIT
- AlicenseNot gradedqualityDmaintenanceBidirectional MCP server that connects Claude with an Obsidian vault, enabling note management, full-text search, graph traversal, and daily notes operations.MIT
- AlicenseNot gradedqualityCmaintenanceRemote MCP server for Obsidian vaults, enabling secure access to markdown notes from Claude clients without the Obsidian desktop app. Provides tools for searching, reading, listing recent notes, resolving daily notes, and creating/appending notes via HTTPS.MIT
- AlicenseNot gradedqualityDmaintenanceEnables MCP-capable assistants to securely search, read, create, edit, move, and delete notes in a private Obsidian vault via Cloudflare, using official Obsidian Sync and OAuth-protected tools.671 npmAGPL 3.0