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, 터널이 필요 없습니다. Agents SDK를 사용하는 Cloudflare 인프라만으로 적절한 MCP 서버를 구축할 수 있습니다.

아키텍처

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)

컨테이너는 단일 진실 공급원(Single Source of Truth)입니다. obsidian-headless를 실행하여 Obsidian Sync와 동기화하고 파일 작업을 위한 HTTP API를 노출합니다. Worker는 모든 MCP 도구 호출을 컨테이너의 API로 프록시합니다.

Related MCP server: obsidian-mcp

MCP 도구

도구

설명

list_notes

경로, 크기, 날짜를 포함한 모든 마크다운 노트 나열

read_note

경로를 통해 노트의 전체 내용 읽기

search_notes

스니펫과 함께 모든 노트에 대한 전체 텍스트 검색

write_note

노트 생성 또는 덮어쓰기

append_to_note

기존 노트에 내용 추가(또는 생성)

delete_note

노트 삭제

create_folder

폴더 생성(중간 디렉토리 포함)

delete_folder

폴더 삭제(비어 있거나 재귀적)

list_folders

경로의 하위 폴더 나열

사전 요구 사항

  • Cloudflare 계정 (Workers 유료 플랜, 월 $5)

  • 활성화된 Obsidian Sync 구독

  • 워크스테이션에 Node.js 22+ 설치

  • wrangler CLI: npm install -g wrangler

설정

0. Wrangler 로그인

wrangler login

모든 필수 범위는 기본적으로 부여됩니다.

1. Obsidian 인증 토큰 생성

워크스테이션에서 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 파일을 Obsidian 자격 증명 및 선택적 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.<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는 요청을 컨테이너의 HTTP API로 프록시하고, API는 /vault에서 직접 읽습니다.

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를 배치하여 감사 로그가 포함된 ID 기반 SSO를 구현하고 코드 변경 없이 적용하세요.

  • OAuth: GitHub/Google OAuth 흐름을 위해 workers-oauth-provider를 통합하세요.

컨테이너 인증

obsidian-headless가 ob login을 위해 --token 또는 환경 변수 기반 인증을 지원하는지 확인하여 대화형 프롬프트를 피하세요. 지원하지 않는 경우, 1회성 대화형 로그인에서 인증 세션을 유지하고 컨테이너 시작 시 복원하세요.

컨테이너 재시작 복원력

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 → 암호화에서 설정한 별도의 종단간 암호화 비밀번호입니다. 볼트가 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