[Obsidian Claude] Claude Code와 노트 지식베이스 연결해서 쓰는 방법

 

안녕하세요. 재아군의 관찰인생입니다.

오늘은 Obsidian과 Claude Code를 연결해서 사용하는 방법을 정리해보겠습니다. 단순히 “노트를 AI가 읽게 한다”가 아니라, Obsidian vault를 개인 지식베이스로 만들고 Claude Code가 그 안의 Markdown 파일을 읽고, 정리하고, 새 노트로 확장하게 만드는 워크플로우입니다.

 

 

현재 Obsidian과 Claude Code가 하나의 공식 버튼으로 완전히 붙어 있는 구조라기보다는, Obsidian이 로컬 Markdown 파일을 저장한다는 특성과 Claude Code가 로컬 파일·MCP 도구와 연결될 수 있다는 특성을 활용하는 방식입니다.

 

핵심 요약: Obsidian vault는 일반 폴더이자 Markdown 파일 묶음입니다. Claude Code에서 이 폴더를 작업 디렉터리로 열거나, MCP filesystem 서버로 vault 경로를 연결하면 Claude가 내 노트를 읽고 정리하는 작업 보조자가 됩니다.

1. Obsidian Claude 연결의 핵심 구조

Obsidian은 노트를 자체 데이터베이스에 가두지 않습니다. 공식 문서 기준으로 Obsidian vault는 로컬 파일 시스템의 폴더이며, 노트는 Markdown 형식의 일반 텍스트 파일입니다. 이 점이 Claude Code와 연결할 때 가장 중요합니다.

즉, Claude Code 입장에서 Obsidian vault는 “특별한 앱 내부 데이터”가 아니라 읽고 쓸 수 있는 문서 폴더입니다. 그래서 Claude Code를 vault 폴더에서 실행하거나, MCP로 vault 경로를 노출하면 노트 정리, 요약, 태깅, 목차 생성, 초안 작성 같은 작업이 가능해집니다.

구성 요소	역할	핵심 포인트
Obsidian	Markdown 노트 작성·링크·검색	vault는 일반 폴더
Claude Code	파일 읽기, 편집, 구조화 작업	프롬프트로 노트 작업 지시
MCP	외부 도구·파일 시스템 연결	경로와 권한을 제한해야 안전

2. 준비물: vault 경로와 백업부터 확인하기

가장 먼저 해야 할 일은 Obsidian vault의 실제 폴더 경로를 확인하는 것입니다. Obsidian에서 vault는 보통 ~/Documents, iCloud Drive, Dropbox, OneDrive, Git으로 관리하는 폴더 안에 있습니다.

Claude Code가 노트 파일을 수정할 수 있게 만들기 전에 반드시 백업 전략을 정해두세요. AI가 잘못된 방향으로 많은 파일을 수정하면 복구가 번거로워질 수 있습니다. Git을 쓰거나, Obsidian Sync/클라우드 동기화의 버전 복구 기능을 확인해두는 것이 좋습니다.

# 예시: vault 폴더 확인
cd "$HOME/Documents/ObsidianVault"
ls

# Git으로 백업하는 경우
git status
git add .
git commit -m "backup before claude code workflow"

3. 방법 1: Claude Code를 vault 폴더에서 바로 실행하기

가장 단순하고 안정적인 방식은 Obsidian vault 폴더를 하나의 프로젝트처럼 여는 것입니다. Obsidian 노트가 Markdown 파일이기 때문에 별도 플러그인 없이도 Claude Code가 파일 구조를 읽고 작업할 수 있습니다.

cd "$HOME/Documents/ObsidianVault"
claude

이 상태에서 Claude Code에는 다음처럼 요청할 수 있습니다.

내 vault의 PARA 구조를 분석해줘.
중복된 노트 제목을 찾아줘.
AI 관련 노트 20개를 읽고 MOC(Map of Content)를 만들어줘.
최근 작성한 회의록에서 액션 아이템만 추출해서 Tasks/Inbox.md에 정리해줘.

이 방법의 장점은 단순함입니다. Claude Code가 현재 폴더 안의 파일을 기준으로 작업하므로 설정이 적고, 문제 발생 시 어떤 파일을 바꿨는지 추적하기 쉽습니다. 개인 vault를 혼자 쓰는 경우라면 이 방식부터 시작하는 것이 좋습니다.

4. 방법 2: MCP filesystem으로 vault 연결하기

두 번째 방법은 Claude Code의 MCP(Model Context Protocol) 기능을 사용하는 것입니다. Anthropic 문서에 따르면 Claude Code는 MCP 서버를 통해 외부 도구와 데이터 소스에 연결할 수 있고, 설정 범위도 local, project, user로 나눌 수 있습니다.

Obsidian vault를 MCP로 연결할 때는 일반적으로 filesystem 계열 MCP 서버를 사용합니다. 핵심은 Claude가 접근해도 되는 경로를 vault 폴더로 제한하는 것입니다.

# 개념 예시: Obsidian vault만 접근하도록 MCP 서버 추가
claude mcp add obsidian-vault --scope user -- npx -y @modelcontextprotocol/server-filesystem "$HOME/Documents/ObsidianVault"

# 연결된 MCP 서버 확인
claude mcp list

# Claude Code 안에서 MCP 상태 확인
/mcp

패키지 옵션이나 실행 인자는 MCP 서버 버전에 따라 달라질 수 있습니다. 따라서 실제 설정 전에는 사용하려는 filesystem MCP 서버의 README와 Claude Code의 MCP 문서를 함께 확인해야 합니다.

5. 추천 vault 구조: AI가 읽기 좋은 노트 시스템

Claude Code와 함께 쓸 vault는 사람이 보기 좋은 구조와 AI가 탐색하기 좋은 구조가 함께 필요합니다. 파일명이 제각각이고 폴더가 너무 깊으면 Claude가 작업 범위를 파악하는 데 비용이 커집니다.

ObsidianVault/
  00_Inbox/
  10_Projects/
  20_Areas/
  30_Resources/
  40_Archive/
  _templates/
  _index/
    AI.md
    Coding.md
    Writing.md

특히 _index나 MOC 노트를 만들어두면 Claude Code가 전체 지식 구조를 파악하기 쉬워집니다. 예를 들어 _index/AI.md에는 AI 관련 핵심 노트 링크를 모아두고, Claude에게 “이 인덱스를 기준으로 관련 노트를 확장해줘”라고 요청할 수 있습니다.

폴더	용도	Claude Code 활용
00_Inbox	임시 메모	분류, 제목 정리, 태그 추천
10_Projects	진행 중인 일	액션 아이템, 회고, 체크리스트 생성
30_Resources	학습 자료	요약, 연결 노트 생성, 키워드 추출
_index	주제별 지도	MOC 자동 갱신

6. 실전 프롬프트: Claude Code에게 이렇게 지시하세요

Obsidian vault 작업은 “알아서 정리해줘”보다 범위, 출력 위치, 수정 규칙을 명확히 주는 편이 훨씬 안전합니다. 특히 기존 노트를 덮어쓰지 않도록 지시하는 것이 중요합니다.

중복 노트 정리

vault 전체에서 제목이 비슷하거나 내용이 겹치는 Markdown 노트를 찾아줘.
바로 수정하지 말고 _index/duplicate-note-report.md에 표로 정리해줘.
표에는 파일 경로, 겹치는 주제, 병합 추천 여부, 이유를 넣어줘.

MOC 생성

30_Resources/AI 폴더의 노트를 읽고 _index/AI-MOC.md를 만들어줘.
Obsidian 내부 링크 형식 [[파일명]]을 사용해줘.
입문, 실무, 도구, 프롬프트, 에이전트로 섹션을 나눠줘.

회의록 액션 아이템 추출

10_Projects/ClientA/Meetings 폴더의 최근 회의록 5개에서 액션 아이템만 추출해줘.
기존 회의록은 수정하지 말고 10_Projects/ClientA/action-items.md에 새로 정리해줘.
담당자, 마감일, 근거가 된 회의록 링크를 표로 만들어줘.

7. 보안 주의점: vault 전체를 열어도 되는가?

Obsidian에는 개인 메모, 업무 정보, API 키, 고객 정보가 섞이기 쉽습니다. Claude Code나 MCP에 vault 전체를 연결하기 전에 AI가 읽어도 되는 vault인지를 먼저 판단해야 합니다.

Obsidian 공식 문서도 커뮤니티 플러그인은 파일 접근, 인터넷 연결, 추가 프로그램 설치 같은 권한을 가질 수 있다고 설명합니다. MCP 역시 외부 도구 연결이므로 비슷한 보안 감각이 필요합니다. 신뢰하지 않는 MCP 서버를 설치하거나, 민감한 vault 전체를 무심코 열어두는 습관은 피해야 합니다.

• 개인 일기와 업무 노트가 섞인 vault는 바로 연결하지 않습니다.
• API 키, 비밀번호, 주민등록번호, 고객 정보가 있는 노트는 별도 보관합니다.
• MCP filesystem 경로는 vault 전체보다 작업 폴더 단위로 좁게 제한합니다.
• 대량 수정 전에는 Git 커밋 또는 백업을 먼저 만듭니다.
• 처음에는 “보고서 생성”처럼 읽기 중심 작업부터 시작합니다.

마무리: Obsidian Claude 조합은 지식 정리 자동화의 출발점입니다

Obsidian Claude 조합의 핵심은 Obsidian을 AI 앱으로 바꾸는 것이 아니라, 내가 쌓아둔 Markdown 노트를 Claude Code가 읽고 정리할 수 있는 작업 가능한 지식베이스로 만드는 것입니다.

처음에는 vault 폴더에서 Claude Code를 실행해 작은 작업부터 시도해보세요. 그다음 반복 작업이 많아지면 MCP filesystem 연결을 검토하면 됩니다. 중요한 것은 연결 자체가 아니라, 노트 구조와 권한 범위를 잘 설계하는 것입니다.

 

 

참고 자료

• Anthropic Docs: Connect Claude Code to tools via MCP
• Anthropic Docs: MCP in the Claude Code SDK
• Obsidian Help: How Obsidian stores data
• Obsidian Help: Plugin security

 

 

Obsidian Claude 워크플로우는 한 번에 완성하기보다, 읽기 전용 분석 → 새 파일 생성 → 제한된 범위 수정 순서로 확장하는 것이 가장 안전합니다.