Skip to main content
Glama
Obsidian Vault MCP Server

Obsidian Vault MCP Server

by JonHollander

通过 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 工具

工具

描述

list_notes

列出所有带有路径、大小和日期的 Markdown 笔记

read_note

按路径读取笔记的全部内容

search_notes

在所有笔记中进行全文搜索并显示片段

write_note

创建或覆盖笔记

append_to_note

追加到现有笔记(或创建它)

delete_note

删除笔记

create_folder

创建文件夹(包含中间目录)

delete_folder

删除文件夹(空文件夹或递归删除)

list_folders

列出路径下的直接子文件夹

先决条件

  • 拥有 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

成本

服务

用途

成本

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。

组件参考

组件

作用

obsidian-headless

官方 Obsidian CLI,无头同步库

McpAgent (Agents SDK)

处理 MCP 传输、会话、身份验证

McpServer (MCP SDK)

工具注册、JSON-RPC 协议

Cloudflare Containers

在 Worker 旁边运行同步进程

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      This 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.
      18
      26 npm
      15
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Bidirectional MCP server that connects Claude with an Obsidian vault, enabling note management, full-text search, graph traversal, and daily notes operations.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Remote 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      AGPL 3.0