Claude Code와 Obsidian MCP 연동 가이드

소개

Claude Code는 Anthropic의 공식 CLI 도구로, MCP(Model Context Protocol)를 통해 다양한 외부 도구와 연동할 수 있습니다. 이 가이드에서는 Claude Code와 Obsidian을 연동하여 AI 에이전트가 여러분의 노트를 읽고 편집할 수 있도록 설정하는 방법을 소개합니다.

MCP(Model Context Protocol)란?

MCP는 AI 모델이 외부 데이터 소스 및 도구와 상호작용할 수 있게 해주는 표준 프로토콜입니다. Claude Code는 MCP를 통해 다음과 같은 작업이 가능합니다:

• 파일 시스템 접근
• 데이터베이스 연동
• API 호출
• Obsidian vault 관리

Obsidian이란?

Obsidian은 마크다운 기반의 강력한 지식 관리 도구입니다. 다음과 같은 특징이 있습니다:

핵심 특징

1. 로컬 우선(Local-first): 모든 노트가 여러분의 컴퓨터에 일반 마크다운 파일로 저장됩니다. 데이터 소유권이 완전히 여러분에게 있습니다.

2. 양방향 링크(Bidirectional Links): [[노트 제목]] 형식으로 노트 간 연결을 만들 수 있으며, 역링크도 자동으로 추적됩니다.

3. 그래프 뷰(Graph View): 노트 간의 연결 관계를 시각적으로 확인할 수 있어, 아이디어 간 관계를 한눈에 파악할 수 있습니다.

4. 플러그인 생태계: 강력한 커뮤니티 플러그인 시스템으로 기능을 확장할 수 있습니다.

5. 개인 지식 베이스: 프로젝트 문서, 학습 노트, 업무 일지, 아이디어 메모 등을 체계적으로 관리할 수 있습니다.

실제 활용 사례

Obsidian은 다음과 같은 용도로 널리 사용됩니다:

• 프로젝트 관리: 작업 일지, 마일스톤, 이슈 트래킹
• 기술 문서화: API 문서, 시스템 아키텍처, 코드 분석
• 학습 노트: 강의 내용, 책 요약, 연구 자료
• 개인 위키: 레시피, 여행 계획, 독서 목록
• Zettelkasten: 영구 노트 작성을 통한 지식 축적

Obsidian과 Claude Code 연동의 장점

1. 컨텍스트 인식 기반 AI 응답

Claude Code가 여러분의 Obsidian vault에 접근할 수 있으면, 축적된 지식을 바탕으로 더 정확하고 맥락에 맞는 답변을 제공합니다.

작동 원리:

사용자: "지난주 작업 내용을 바탕으로 이번 주 계획을 세워줘"

Claude Code → MCP → Obsidian vault
         ↓
"Project 관리/2025-10-19 작업 일지.md" 읽기
"레거시 분석/생산관리 레거시 화면 분석.md" 참조
         ↓
프로젝트 맥락을 이해한 상태에서 답변 생성

2. 프로젝트 지식 베이스 활용

여러분이 Obsidian에 정리해둔 모든 문서가 Claude의 작업 컨텍스트가 됩니다.

실제 예시 (현재 연결된 vault 기준):

사용자: "생산 모듈 마이그레이션할 때 주의할 점이 뭐야?"

Claude가 자동으로 참조:
- "생산 모듈 마이그레이션 가이드.md"
- "Project 관리/DevExpress 마이그레이션 프로젝트.md"
- "레거시 분석/화면/생산관리 레거시 화면 분석.md"
- "Migration/마이그레이션 이슈 트래킹.md"

→ 프로젝트별 특수 상황을 반영한 맞춤 답변 제공

3. 일관된 문서 관리

Claude가 여러분의 문서 구조와 작성 스타일을 학습하여 일관된 형식으로 문서를 생성하고 수정합니다.

예시:

사용자: "오늘 작업 일지를 작성해줘"

Claude가:
1. 기존 작업 일지 템플릿 분석
   ("Project 관리/2025-10-19 작업 일지.md" 참조)
2. 동일한 구조와 형식으로 새 파일 생성
3. 프로젝트별 진행 상황 자동 반영

4. 지식 그래프 구축 및 연결

Claude가 노트 간의 관계를 이해하고 자동으로 관련 문서를 연결합니다.

작동 방식:

사용자: "MES 데이터베이스 스키마에 대한 인덱스 페이지 만들어줘"

Claude가:
1. vault 전체 검색으로 관련 파일 발견
   - "MES 데이터베이스 스키마.md"
   - "MES 데이터베이스 DDL.sql"
   - "Backend/백엔드 API 테이블 및 Controller 매핑.md"
2. 자동으로 양방향 링크 생성
3. 카테고리별로 정리된 인덱스 페이지 생성

5. 반복 작업 자동화

정형화된 작업을 Claude에게 맡겨 시간을 절약할 수 있습니다.

활용 예시:

• 일일 스탠드업 리포트 생성: 작업 일지를 분석해 요약 생성
• 주간/월간 리뷰: 기간별 작업 내용 취합 및 분석
• 문서 업데이트 추적: 변경된 API나 스키마 관련 문서 자동 업데이트
• 태그 정리: 일관된 태그 체계로 자동 정리

6. 프로젝트 전체 맥락 파악

대규모 프로젝트에서 특히 유용합니다.

시나리오:

사용자: "생산 모듈에서 사용하는 모든 API 엔드포인트를 정리해줘"

Claude가:
1. "Backend/생산 모듈 백엔드 API 분석.md" 읽기
2. "Project 관리/API 변경 사항.md" 참조
3. "레거시 분석" 폴더 전체 스캔
4. 모든 정보를 종합하여 완전한 API 목록 생성

→ 여러 문서에 흩어진 정보를 한 번에 통합

7. RAG(Retrieval-Augmented Generation) 구현

Obsidian vault는 사실상 개인화된 RAG 시스템이 됩니다.

원리:

일반 Claude:
질문 → AI 모델 → 일반적인 답변

Claude + Obsidian MCP:
질문 → vault에서 관련 문서 검색 → AI 모델 + 실제 문서 내용 → 정확한 맞춤 답변

장점:

• 프로젝트 특정 용어와 컨텍스트 반영
• 실제 데이터 기반 답변 (환각 감소)
• 회사/팀 고유의 워크플로우 이해

필요 조건

• Claude Code 설치
• Obsidian 설치

Obsidian MCP 플러그인 설치

이 방식은 Obsidian 플러그인을 통해 MCP 서버를 구동하는 방식입니다. 별도의 Node.js 환경이나 npm 설치가 필요 없습니다.

1. 플러그인 다운로드

GitHub releases 페이지에서 최신 버전의 플러그인 파일을 다운로드합니다.

필요한 파일 3개:

• main.js
• manifest.json
• styles.css

다운로드 명령어 (Windows PowerShell 또는 Git Bash):

# 플러그인 디렉토리 생성
mkdir -p "C:\path\to\your\vault\.obsidian\plugins\obsidian-claude-code-mcp"
cd "C:\path\to\your\vault\.obsidian\plugins\obsidian-claude-code-mcp"

# 파일 다운로드
curl -L -O https://github.com/iansinnott/obsidian-claude-code-mcp/releases/download/1.1.8/main.js
curl -L -O https://github.com/iansinnott/obsidian-claude-code-mcp/releases/download/1.1.8/manifest.json
curl -L -O https://github.com/iansinnott/obsidian-claude-code-mcp/releases/download/1.1.8/styles.css

macOS/Linux:

# 플러그인 디렉토리 생성
mkdir -p ~/Documents/ObsidianVault/.obsidian/plugins/obsidian-claude-code-mcp
cd ~/Documents/ObsidianVault/.obsidian/plugins/obsidian-claude-code-mcp

# 파일 다운로드
curl -L -O https://github.com/iansinnott/obsidian-claude-code-mcp/releases/download/1.1.8/main.js
curl -L -O https://github.com/iansinnott/obsidian-claude-code-mcp/releases/download/1.1.8/manifest.json
curl -L -O https://github.com/iansinnott/obsidian-claude-code-mcp/releases/download/1.1.8/styles.css

중요: C:\path\to\your\vault 또는 ~/Documents/ObsidianVault를 실제 Obsidian vault 경로로 변경하세요.

2. Obsidian에서 플러그인 활성화

1. Obsidian을 실행합니다
2. 설정(Settings) → 커뮤니티 플러그인(Community plugins)으로 이동
3. "Claude Code MCP" 플러그인을 찾아 활성화합니다
4. 플러그인 설정에서 MCP 서버 설정을 확인합니다

3. Claude Code CLI로 MCP 연결

Obsidian 플러그인이 활성화되면 로컬 MCP 서버가 포트 22360에서 실행됩니다. Claude CLI 명령어로 간단하게 연결할 수 있습니다:

claude mcp add --transport sse obsidian http://localhost:22360/sse

명령어 설명:

• claude mcp add: MCP 서버를 추가하는 명령어
• --transport sse: SSE(Server-Sent Events) 전송 방식 사용
• obsidian: MCP 서버의 이름 (원하는 이름으로 변경 가능)
• http://localhost:22360/sse: Obsidian 플러그인이 실행하는 MCP 서버 주소

중요:

• Obsidian이 실행되고 플러그인이 활성화된 상태에서 이 명령어를 실행하세요
• 연결이 성공하면 Claude Code에서 Obsidian vault에 접근할 수 있습니다

3.1 Vault의 Path확인 하는 방법

3.2 연동이 잘 되었는지 확인 하기

사용 가능한 기능

Obsidian MCP 연동을 통해 Claude Code에서 다음 작업이 가능합니다:

1. Vault 파일 목록 조회

vault의 모든 파일을 보여줘

Claude가 mcp__obsidian__get_workspace_files 도구를 사용하여 vault의 모든 파일을 나열합니다.

2. 파일 내용 읽기

"프로젝트 관리/작업 일지.md" 파일을 읽어줘

Claude가 mcp__obsidian__view 도구를 사용하여 특정 파일의 내용을 읽습니다.

3. 파일 내용 수정

"작업 일지.md"의 TODO 섹션에 새로운 태스크를 추가해줘

Claude가 mcp__obsidian__str_replace 또는 mcp__obsidian__insert 도구를 사용하여 파일을 편집합니다.

4. 새 파일 생성

"Blog" 폴더에 새로운 블로그 글을 작성해줘

Claude가 mcp__obsidian__create 도구를 사용하여 새 파일을 생성합니다.

5. 현재 활성 파일 가져오기

지금 열려있는 파일을 분석해줘

Claude가 mcp__obsidian__get_current_file 도구를 사용하여 Obsidian에서 현재 열려있는 파일을 가져옵니다.

실제 사용 예시

예시 1: 일일 작업 일지 자동화

오늘 날짜로 새로운 작업 일지를 만들어줘. 템플릿은 기존 작업 일지를 참고해.

Claude가:

1. 기존 작업 일지 파일을 읽어 템플릿 확인
2. 오늘 날짜로 새 파일 생성
3. 템플릿 적용

예시 2: 노트 정리 및 링크 추가

"프로젝트 A" 관련 파일들을 찾아서 인덱스 페이지를 만들어줘

Claude가:

1. 프로젝트 A 관련 파일 검색
2. 인덱스 파일 생성
3. 각 파일로의 링크 추가

예시 3: 콘텐츠 분석 및 요약

이번 주 작업 일지들을 분석해서 주간 리포트를 작성해줘

Claude가:

1. 이번 주 작업 일지 파일들 조회
2. 각 파일 내용 읽기
3. 요약 및 주간 리포트 생성

고급 활용 팁

1. Obsidian API 직접 사용

mcp__obsidian__obsidian_api 도구를 통해 Obsidian의 TypeScript API를 직접 호출할 수 있습니다:

Obsidian API를 사용해서 모든 태그를 찾아줘

2. 파일 패턴 필터링

파일 목록 조회 시 패턴을 지정할 수 있습니다:

"*.md" 패턴으로 마크다운 파일만 보여줘

3. 특정 라인 범위 읽기

큰 파일의 경우 특정 라인만 읽을 수 있습니다:

"데이터베이스 스키마.md"의 100번째 줄부터 200번째 줄까지 읽어줘

보안 고려사항

• MCP 서버는 vault에 대한 전체 읽기/쓰기 권한을 가집니다
• 민감한 정보가 포함된 vault는 주의해서 사용하세요
• 설정 파일에 경로가 올바른지 확인하세요

문제 해결

MCP 서버가 연결되지 않을 때

1. Obsidian 플러그인 확인:

   • Obsidian 설정 → 커뮤니티 플러그인에서 "Claude Code MCP"가 활성화되어 있는지 확인
   • 플러그인이 목록에 없다면 파일이 올바른 위치에 있는지 확인:
     • .obsidian/plugins/obsidian-claude-code-mcp/ 폴더 확인
     • main.js, manifest.json, styles.css 3개 파일이 모두 있는지 확인

2. Obsidian 재시작:

   • Obsidian을 완전히 종료하고 다시 시작
   • 플러그인 로드 중 오류 메시지가 있는지 확인

3. Claude Code 재시작:

   • mcp_config.json 설정 후 Claude Code를 재시작해야 적용됩니다

4. 플러그인 설정 확인:

   • Obsidian에서 플러그인 설정을 열어 MCP 서버 상태 확인
   • 설정에서 실제 config 디렉토리 경로를 확인할 수 있습니다

파일을 찾을 수 없을 때

• 파일 경로는 vault root를 기준으로 상대 경로로 지정
• 예: "Blog/article.md" (앞에 / 없음)
• Obsidian이 실행 중이어야 MCP 서버가 작동합니다

플러그인이 목록에 나타나지 않을 때

• 커뮤니티 플러그인이 활성화되어 있는지 확인:
  • 설정 → 커뮤니티 플러그인 → "제한 모드 해제(Turn off restricted mode)"
• 플러그인 폴더 이름이 정확한지 확인: obsidian-claude-code-mcp
• Obsidian 개발자 콘솔(Ctrl+Shift+I)에서 에러 메시지 확인

권한 오류

• Obsidian이 vault 폴더에 대한 읽기/쓰기 권한이 있는지 확인
• 중요: Obsidian이 실행 중이어야 MCP 서버가 작동합니다

결론

Claude Code와 Obsidian의 MCP 연동은 노트 관리를 자동화하고 AI의 도움을 받아 더 효율적으로 지식을 관리할 수 있게 해줍니다. 일일 작업 일지 작성, 노트 정리, 콘텐츠 분석 등 다양한 작업을 자동화할 수 있습니다.

이 강력한 도구를 활용하여 여러분의 지식 관리 워크플로우를 한 단계 업그레이드해보세요!

참고 자료

• Claude Code 공식 문서
• MCP 프로토콜 문서
• Obsidian API 문서
• Obsidian Claude Code MCP 플러그인
• 플러그인 최신 릴리즈