Obsidian Vault MCP Server

黑曜石+克劳德通过Cloudflare

使用MCP服务器从Claude（网络、桌面、代码）访问您的黑曜石保险库 Cloudflare Workers+容器。

没有NAS，没有Docker Compose，没有隧道。仅Cloudflare基础设施 用于正确MCP服务器的代理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代理 对容器的API的所有MCP工具调用。

MCP工具

先决条件

• Cloudflare帐户与工人付费计划（每月5美元）
• 活跃的 黑曜石同步 订阅
• 工作站上的Node.js 22+
• wrangler CLI： npm install -g wrangler

设置

0.牧马人登录

wrangler login

默认情况下，所有必需的范围都被授予。

1.生成黑曜石身份验证令牌

工作站上的一次性步骤：

npm install -g obsidian-headless

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

ob sync-list-remote
# Note your vault name

2.配置环境

复制示例env文件并填写您的值：

cp .dev.vars.example .dev.vars

编辑 .dev.vars 使用您的黑曜石凭据和可选的MCP身份验证令牌。 此文件由以下人员使用 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..workers.dev/mcp

4.连接克劳德

Claude.ai（网络）

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

• 网址： https://obsidian-mcp..workers.dev/mcp?token=YOUR_MCP_AUTH_TOKEN
• 将OAuth字段留空——URL中的令牌处理身份验证

克劳德代码

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

克劳德桌面版

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian-vault": {
      "url": "https://obsidian-mcp..workers.dev/mcp"
    }
  }
}

数据如何流动

您在手机上编辑了一条备忘：

1. 黑曜石同步推动变革
2. 集装箱 ob sync --continuous 拉动它 /vault
3. 下次Claude读取或搜索时，Worker将请求代理到

容器的HTTP API，直接从 /vault

克劳德创建了一个注释：

1. 工人收到MCP write_note 呼叫
2. Worker将其代理到容器的HTTP API
3. 容器将文件写入 /vault
4. ob 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 访问：放 零信任访问

在Worker前面，用于基于身份的SSO，具有审核日志，无需更改代码

• OAuth：集成 workers-oauth-provider

GitHub/谷歌OAuth流

容器身份验证

检查是否 obsidian-headless 支持 --token 或基于env-var的身份验证 ob login 以避免交互式提示。如果没有，请从以下位置持久化身份验证会话 一次性交互式登录，并在容器启动时恢复。

容器重启弹性

这 ob sqlite状态文件位于临时容器磁盘上。重启触发 完全重新同步。要修复：在中添加SIGTERM陷阱 entrypoint.sh 这坚持了 状态文件，并在启动时还原。

搜索性能

暴力搜索读取每个 .md 每个查询一个文件——对于\<500个文件很好。 对于较大的保管库，请在中构建搜索索引 第1天 或 工人KV.

附件

当前筛选为 .md 只有。扩展以支持图像、PDF和其他 使用其他工具安装vault附件。

故障排除

Docker必须正在运行 --同步容器需要Docker。跑 docker info 以验证。这 validate 子命令会自动检查这一点。

两个密码 — OBSIDIAN_PASSWORD 是您的黑曜石帐户密码（已使用 登录obsidian.md）。 VAULT_PASSWORD 是单独的端到端加密 在黑曜石中设置密码→ Sync → 加密。离开 VAULT_PASSWORD 如果为空 你的保险库不使用E2EE。

部署不会重新启动容器 — wrangler deploy 不重新启动运行 容器。安装脚本会自动处理此问题。如果手动部署， 重新启动 ./scripts/setup.sh restart.

集装箱原木不在牧马人的尾部 --容器stdout未通过流式传输 wrangler tail.使用 ./scripts/setup.sh container-logs 相反。

组件引用