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: obsidianMCP

MCP 도구

사전 요구 사항

• 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

비용

프로젝트 구조

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를 사용하세요.

구성 요소 참조