Obsidian Vault MCP Server
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 도구
도구 | 설명 |
| 경로, 크기, 날짜를 포함한 모든 마크다운 노트 나열 |
| 경로를 통해 노트의 전체 내용 읽기 |
| 스니펫과 함께 모든 노트에 대한 전체 텍스트 검색 |
| 노트 생성 또는 덮어쓰기 |
| 기존 노트에 내용 추가(또는 생성) |
| 노트 삭제 |
| 폴더 생성(중간 디렉토리 포함) |
| 폴더 삭제(비어 있거나 재귀적) |
| 경로의 하위 폴더 나열 |
사전 요구 사항
Cloudflare 계정 (Workers 유료 플랜, 월 $5)
활성화된 Obsidian Sync 구독
워크스테이션에 Node.js 22+ 설치
wranglerCLI: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 name2. 환경 구성
예제 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 logsMCP 서버가 다음 주소에서 실행됩니다:
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는 요청을 컨테이너의 HTTP API로 프록시하고, API는
/vault에서 직접 읽습니다.
Claude가 노트를 생성할 때:
Worker가 MCP
write_note호출을 수신합니다.Worker가 이를 컨테이너의 HTTP API로 프록시합니다.
컨테이너가 파일을
/vault에 씁니다.ob 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를 배치하여 감사 로그가 포함된 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를 사용하세요.
구성 요소 참조
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
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