aaronsb/obsidian-mcp-plugin

AI에게 당신의 지식 그래프에 대한 의미론적 에이전시(Semantic Agency)를 부여하세요

이 플러그인은 MCP (Model Context Protocol)를 통해 당신의 Obsidian 보관소(Vault)를 AI 어시스턴트와 연결하여, AI가 단순히 고립된 파일이 아닌 연결된 지식 그래프로서 당신의 노트를 이해하고 탐색할 수 있는 능력을 부여합니다. 의미론적 힌트(Semantic hints)와 그래프 탐색(Graph traversal)을 통해, AI는 개념을 탐색하고, 연결을 따라가며, 보관소 전체에 걸쳐 정보를 합성할 수 있는 에이전시(Agency)를 얻게 됩니다.

**MCP (Model Context Protocol)**는 AI 어시스턴트가 외부 도구 및 데이터 소스와 상호작용할 수 있게 해주는 개방형 표준입니다. 이 플러그인은 다음을 포함하여 MCP 호환 클라이언트와 함께 작동합니다:

• Claude Desktop (Anthropic)
• Claude Code/Continue.dev (VS Code)
• 로컬 MCP 서버를 지원하는 모든 플랫폼

선행 조건: Claude Desktop, Claude Code 또는 Continue.dev와 같은 MCP 호환 AI 클라이언트가 필요합니다.

플러그인의 설정 페이지에서 .mcpb 번들을 다운로드하세요 → Claude Desktop 위로 드래그하세요 → 키를 붙여넣으세요. 완료되었습니다.

대부분의 사용자에게는 이것이 설정의 전부입니다. 아래의 번호가 매겨진 단계들은 이를 상세히 설명하며, 그 후 다른 MCP 클라이언트들을 다룹니다.

Obsidian 커뮤니티 플러그인을 통한 방법

• Settings → Community plugins → Browse를 엽니다.
• "Semantic Notes Vault MCP"를 검색합니다.
• 설치 및 활성화합니다 — 또는 플러그인 목록에서 직접 설치합니다.

BRAT을 통한 방법 (베타 테스트용)

• BRAT을 설치합니다.
• 베타 플러그인을 추가합니다:
  aaronsb/obsidian-mcp-plugin

대상 사용자별로 정렬된 세 가지 온보딩 경로가 있습니다. 세 가지 방법 모두 플러그인의 Settings 탭에 복사 가능한 값과 함께 표시됩니다.

📦 → 🤖 Claude Desktop — 원클릭 .mcpb 설치 (권장)

obsidian-mcp-<version>.mcpb를 다운로드하세요 — 플러그인의 Settings 탭(설정 페이지의 버튼) 또는 최신 릴리스에서 다운로드할 수 있습니다 — 그런 다음 Claude Desktop 창 위로 드래그하거나 파일을 더블 클릭하세요. Claude Desktop이 두 개의 필드가 있는 설치 대화 상자를 엽니다 — 플러그인의 Settings 탭에 표시된 URL과 API 키를 붙여넣고, Save를 누르면 완료됩니다.

교차 플랫폼 참고 사항: .mcpb

.mcpb 파일은 Claude Desktop에 내장된 핸들러를 통해 설치됩니다. 시스템에서 더블 클릭으로 Claude가 실행되지 않는 경우, 파일을 Claude Desktop 창으로 드래그하거나, 마우스 오른쪽 버튼 클릭 → "다음으로 열기(Open with…)\

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain \/path/to/vault/.obsidian/plugins/semantic-vault-mcp/certificates/default.crt

** NODE_EXTRA_CA_CERTS** (Claude Code 및 기타 Bun 기반 런타임(runtimes)에 필수):

Bun은 TLS 신뢰를 위해 macOS 시스템 키체인(system keychain)을 참조하지 않습니다. 따라서 키체인 접근(Keychain Access)을 통해 인증서를 신뢰하는 것만으로는 아무런 효과가 없으며, 이는 Claude Code에서 HTTPS 연결이 실패하는 거의 항상 발생하는 실제 원인입니다. Bun은 오직 NODE_EXTRA_CA_CERTS에 나열된 인증서만 인정합니다.

:

# 플러그인 인증서를 직접 가리키거나, 기존 CA 번들(bundle)에 추가합니다:
export NODE_EXTRA_CA_CERTS=/path/to/vault/.obsidian/plugins/semantic-vault-mcp/certificates/default.crt
# macOS 독(dock)에서 실행되는 GUI 앱(Claude Code 포함)에 전파합니다:
...

플러그인이 인증서를 재생성할 때마다(예: 1년의 유효 기간이 만료된 후) 이 과정을 다시 실행하십시오.

NODE_TLS_REJECT_UNAUTHORIZED=0를 사용하는 것은 프로세스 전체에서 TLS 검증 과정을 비활성화합니다. 이는 이 플러그인뿐만 아니라 클라이언트가 수행하는 모든 HTTPS 연결에 적용되며, 정당한 인증서 문제(만료, 취소, 변조 등)를 은폐합니다. 대신 인증서를 명시적으로 신뢰하십시오.

연결되면, 단순히 AI 어시스턴트와 당신의 노트에 대해 대화하세요! 예를 들어:

• "프로젝트 X에 대한 나의 최근 생각은 무엇인가요?"
• "나의 심리학 노트와 철학 노트 사이의 연결 고리를 찾아줘"
• "이번 주 회의록을 요약해줘"
• "Y에 대한 나의 아이디어를 연결하는 새로운 노트를 만들어줘"

이제 당신의 AI 어시스턴트는 다음과 같은 능력을 갖게 됩니다:

• 보관소(vault)의 링크 구조 탐색
• 모든 노트를 의미론적(semantically)으로 검색
• 노트 읽기, 편집 및 생성
• 지식 그래프(knowledge graph) 분석
• Dataview 쿼리 작업 (설치된 경우)
• Obsidian Bases (데이터베이스 뷰) 관리

전통적인 파일 접근 방식은 AI에게 한 번에 하나의 문서만 보여주는 좁은 시야를 제공합니다. 이 플러그인은 이를 **의미론적 에이전시 (semantic agency)**로 변환합니다:

그래프 탐색 (Graph Navigation): AI가 노트 간의 링크를 따라가며 관계와 문맥을 이해합니다.
개념 발견 (Concept Discovery): 의미론적 검색 (Semantic search)을 통해 보관함(vault) 전체에서 관련된 아이디어를 찾아냅니다.
문맥 인식 (Contextual Awareness): AI가 지식 구조 내에서 정보가 어디에 위치하는지 이해합니다.
지능적 합성 (Intelligent Synthesis): 여러 노트의 파편들을 결합하여 복잡한 질문에 답변합니다.

이 플러그인은 AI에게 포괄적인 보관함 접근 권한을 부여하는 8가지 의미론적 도구 그룹을 제공합니다:

도구	목적	주요 작업
📁 vault	파일 작업	list, read, create, search, move, split, combine
✏️ edit	콘텐츠 수정	window editing, append, patch sections
👁️ view	콘텐츠 표시	view files, windows, active note
🕸️ graph	링크 탐색	traverse, find paths, analyze connections
💡 workflow	문맥적 힌트	상태에 기반한 다음 작업 제안
📊 dataview	노트 쿼리	DQL 쿼리 실행 (설치된 경우)
🗃️ bases	데이터베이스 뷰	Bases 쿼리 및 내보내기 (사용 가능한 경우)
ℹ️ system	보관함 정보	서버 상태, 명령, 웹 페치 (web fetch)

각 도구 및 기능에 대한 상세 문서:

• 📁 Vault Operations - 파일 관리 및 검색
• ✏️ Edit Operations - 콘텐츠 수정 전략
• 🕸️ Graph Navigation - 링크 순회 및 분석
• 📊 Dataview Integration - 쿼리 언어 지원
• 🔐 Security & Authentication - API 키 및 권한
• 🔧 Configuration - 서버 설정 및 옵션
• ❓ Troubleshooting - 일반적인 문제 및 해결 방법

이 플러그인은 단순히 AI에게 파일 접근 권한을 주는 것이 아니라, **의미론적 이해 (semantic understanding)**를 제공합니다:

사용자: "머신러닝 최적화에 관한 내 연구를 요약해줘"
AI가 의미론적 도구를 사용하여:
1. ML 최적화 개념이 포함된 노트를 검색
...

사용자: "철학과 인지 과학에 관한 내 노트들 사이에 어떤 연결 고리가 있어?"
AI가 그래프 도구를 사용하여:
1. 두 주제가 모두 태그된 노트를 찾음
...

• 고급 쿼리 연산자:
  tag:, path:, content:

• 정규 표현식 (Regular expressions) 및 구절 매칭 (phrase matching)

• 관련성 순위 지정 (Relevance ranking) 및 스니펫 추출 (snippet extraction)

• 깊이 제어 (depth control)를 포함한 멀티 홉 탐색 (Multi-hop traversal)

• 백링크 (Backlink) 및 포워드 링크 (forward-link) 분석

• 개념 간 경로 찾기 (Path finding)

• 태그 기반 탐색 (Tag-based navigation)

• 편집을 위한 퍼지 텍스트 매칭 (Fuzzy text matching)

• 구조 인식 수정 (Structure-aware modifications) (제목, 블록)

• 일괄 작업 (Batch operations) (분할, 결합, 이동)

• 템플릿 지원 (Template support)

• Dataview 쿼리 실행

• Bases 데이터베이스 작업

• 웹 콘텐츠 가져오기 (Web content fetching)

• 안전을 위한 읽기 전용 모드 (Read-only mode)

다음 경로를 통해 설정에 접근할 수 있습니다: 설정 (Settings) → 커뮤니티 플러그인 (Community plugins) → Semantic MCP

주요 설정 옵션:

서버 포트 (Server Ports): HTTP (3001) 및 HTTPS (3443)
인증 (Authentication): API 키 보호
보안 (Security): 경로 검증 (Path validation) 및 권한
성능 (Performance): 커넥션 풀링 (Connection pooling) 및 캐싱 (Caching)

이슈 (Issues): GitHub Issues
토론 (Discussions): GitHub Discussions
후원 (Sponsor): GitHub Sponsors