[Claude] Claude Code(클로드 코드) Obsidian(옵시디언) MCP 연동 가이드 - 맥락 더 잘 주입하기

Claude는 세션이 끊기면 모든 걸 잊는다. 이 문제를 Obsidian MCP로 해결했다. MCPVault로 로컬 vault를 Claude의 컨텍스트로 연결하는 방법을 정리한다.

 

문서화 저장 방식을 Notion에서 Obsidian으로 넘어온 이유도 여기에 있다. 어제 뭘 짰는지, 어떤 맥락이었는지 매번 다시 설명해야 하는 게 한계였다. 노션도 MCP가 있지만 결국 노션 서버를 타야 한다. Obsidian은 다르다. 내 컴퓨터에 있는 .md 파일을 Claude가 직접 읽는다. 내 노트가 곧 Claude의 컨텍스트가 된다.

 

Obsidian MCP를 연결하면 Claude가 그 파일을 직접 읽고 쓴다. 세션이 끊겨도, 한 달 뒤에 돌아와도 내 프로젝트 맥락이 그대로 남아 있다.

 

이번 글에서는 Obsidian을 왜 쓰는지부터 시작해서, vault 구조를 어떻게 잡는지, MCPVault로 Claude Code와 연동하는 전 과정을 정리한다.

---

Obsidian이란

옵시디언은 마크다운 기반의 로컬 저장형 노트 앱이다. 2020년 출시 이후 개발자, 연구자, 콘텐츠 기획자 사이에서 빠르게 퍼졌고, 2026년 현재 2,000개가 넘는 커뮤니티 플러그인이 존재한다.

 

다른 노트 앱과 가장 큰 차이점은 데이터 구조다. 노션이나 에버노트는 데이터가 서버에 있어서 내 컴퓨터에 파일이 없다. Obsidian은 Vault로 지정한 폴더 안의 모든 .md 파일이 그냥 로컬 파일이라 파인더(Finder)에서 직접 열거나 메모장으로도 편집할 수 있다.

 

이게 MCP 연동의 전제 조건이다. AI가 읽고 쓸 수 있는 건 결국 파일이기 때문이다.

 

Obsidian을 사용하는 이유

1. 데이터 주권

서비스가 망해도 내 노트는 사라지지 않는다. 로컬 .md 파일이 있는 한 다른 앱으로 이전하는 것도 자유롭다. AI 도구가 확산될수록 데이터 주권에 대한 관심도 커지고 있고, 그 흐름 속에서 Obsidian의 로컬 저장 방식이 하나의 대안으로 주목받고 있다.

 

2. 연결 기반 사고 ([[백링크]])

기존 노트 앱이 폴더 안에 파일을 넣는 계층 구조라면, Obsidian은 노트와 노트를 링크로 연결한다. [[노트명]]으로 연결하면 역링크도 자동으로 추적되고, 내 생각의 구조가 그래프 뷰로 눈에 보이기 시작한다.

 

3. .md 파일 = Claude가 가장 잘 읽는 포맷

Claude Code는 마크다운을 네이티브로 이해해서 헤딩 구조, 코드 블록, 체크리스트, 프론트매터까지 그대로 파싱한다. Obsidian이 .md로 저장한다는 건 별도 변환 없이 Claude Code가 바로 쓸 수 있다는 뜻이다. 원격 클라우드 API가 아니라 로컬 파일시스템을 직접 읽으니 속도도 빠르고 구조도 보존된다.

 

볼트(Vault) 구조 잡기

Obsidian에서 Vault는 모든 노트가 저장되는 루트 폴더다. 구조를 어떻게 잡느냐에 따라 나중에 Claude가 얼마나 잘 찾아주는지가 달라진다.

 

보통 가장 많이 쓰이는 방식은 PARA 구조다.

📁 my-vault/
├── 00_Inbox/
├── 10_Projects/
│   └── 사이드프로젝트/
│       ├── 개요.md
│       ├── 작업일지/
│       └── 이슈트래킹.md
├── 20_Areas/
├── 30_Resources/
└── 40_Archive/

 

PARA의 핵심은 주제별 분류가 아니라 실행 가능성(Actionability) 기준으로 나눈다는 것이다.

지금 손대고 있는 건 Projects, 장기적으로 유지하는 건 Areas, 나중에 참고할 건 Resources, 끝난 건 Archive로 보낸다.

 

Projects/Areas로 나눠두면 "지난주 작업 요약해줘" 같은 요청에서 Claude Code가 10_Projects/ 안만 봐도 되니 전체 vault를 뒤지는 것보다 훨씬 정확하게 찾는다. 폴더명이 곧 Claude Code에게 주는 힌트인 셈이다.

 

처음부터 완벽한 구조를 만들 필요는 없다. Obsidian은 폴더 중심이 아니라 링크 중심 도구라 일단 쓰면서 다듬어가는 게 훨씬 효율적이다.

 

⭐️ Claude Code MCP 연동 — MCPVault 사용

MCP로 Obsidian을 연결하는 방법은 여러 가지가 있는데, 그 중 MCPVault(bitbonsai)를 선택했다.

https://github.com/bitbonsai/mcpvault

GitHub - bitbonsai/mcpvault: A lightweight Model Context Protocol (MCP) server for safe Obsidian vault access

 

MCPVault를 선택한 큰 이유는 Obsidian이 켜져 있지 않아도 동작한다.

 

가장 많이 쓰이는 mcp-obsidian(MarkusPfundstein)은 Obsidian 안에 Local REST API 플러그인을 설치해야 하고 Obsidian이 실행 중일 때만 쓸 수 있다. MCPVault는 .md 파일을 직접 읽는 방식이라 앱 실행 여부와 무관하고, BM25 검색에 프론트매터 손상 없이 14가지 도구를 지원한다.

 

1단계) Obsidian 설치

obsidian.md에서 다운로드 후 설치한다. macOS에서 "확인되지 않은 개발자" 경고가 뜨면 시스템 설정 → 개인 정보 보호 및 보안 → "그래도 열기"를 클릭하면 된다.

 

설치 후 실행하면 Vault 생성 화면이 나오는데 "Create new vault"를 클릭하고 경로를 지정한다. 로컬 아무 경로나 써도 되고, Dropbox나 Google Drive 같은 클라우드 스토리지 경로를 지정하면 기기 간 동기화도 된다. 

 

나는 Mac 유저라 iCloud Drive를 사용했고, 이렇게 iCloud Drive에 두면 기기 간 동기화도 자동으로 된다.

# 로컬
~/Documents/my-vault

# iCloud Drive (Mac 유저)
~/Library/Mobile Documents/com~apple~CloudDocs/my-vault

my-vault 부분은 본인이 지정한 vault 폴더명으로 바꾸면 된다.

주의할 점) Mobile Documents처럼 경로에 스페이스가 포함되어 있어서 터미널에서 직접 입력할 때는 따옴표로 감싸거나 백슬래시로 이스케이프 처리해야 한다. JSON 설정 파일 안에서는 이스케이프 없이 그대로 써도 된다.

# 방법 1) 큰따옴표 — 공백 그대로
"/Users/본인계정/Library/Mobile Documents/com~apple~CloudDocs/my-vault"

# 방법 2) 백슬래시 이스케이프 — 따옴표 없이
/Users/본인계정/Library/Mobile\ Documents/com~apple~CloudDocs/my-vault

 

2단계) Claude Code에 Obsidian MCP 등록

터미널에서 아래 명령어 실행한다. 이후 등록됐는지 확인은 claude mcp list로 한다.

claude mcp add obsidian -- npx @bitbonsai/mcpvault@latest \
  "/Users/본인계정/Library/Mobile Documents/com~apple~CloudDocs/my-vault"

 

3단계) 연결 확인

Claude Code 새 세션에서 실행 후 아래와 같이 물어본다.

• "내 Obsidian vault에 어떤 파일이 있어?"

파일 목록이 나오면 성공이다.

 

옵시디언 연동 후 달라진 것

• "지난주 프로젝트 작업 내용 요약해줘" → 작업일지 파일 읽고 요약
• "서비스 문서 기반으로 API 스펙 초안 잡아줘" → vault 내 문서 참조해서 생성
• "오늘 작업 일지 작성해줘" → 기존 템플릿 참고해서 동일한 형식으로 새 파일 생성

노트가 쌓일수록 Claude가 더 잘 대답한다. vault가 단순 저장소에서 AI와 함께 쓰는 두 번째 뇌로 바뀌는 느낌이다.

 

아래는 현재 나의 Obsidian 그래프 구조로 하나씩 링크드하고 커질때마다 뿌듯하다!!

 

현재 나의 Obsidian 그래프 구조