Obsidian용 MCP 도구

기능 | 설치 | 구성 | 문제 해결 | 보안 | 개발 | 지원

Obsidian용 MCP Tools를 사용하면 Claude Desktop과 같은 AI 애플리케이션이 모델 컨텍스트 프로토콜(MCP)을 통해 Obsidian 볼트에 안전하게 액세스하고 작업할 수 있습니다. MCP는 AI 애플리케이션이 보안 및 사용자 제어를 유지하면서 외부 데이터 소스 및 도구와 상호 작용하는 방식을 표준화하는 개방형 프로토콜입니다. [^2]

이 플러그인은 두 부분으로 구성되어 있습니다.

1. 볼트에 MCP 기능을 추가하는 Obsidian 플러그인
2. AI 애플리케이션과의 통신을 처리하는 로컬 MCP 서버

이 플러그인을 설치하면 두 구성 요소를 모두 설정하는 데 도움이 됩니다. MCP 서버는 사용자의 Vault와 Claude Desktop과 같은 AI 애플리케이션 간의 안전한 연결고리 역할을 합니다. 즉, AI 비서가 사용자의 메모를 읽고, 템플릿을 실행하고, 의미 검색을 수행할 수 있지만, 사용자가 허용하고 서버의 보안 API를 통해서만 가능합니다. 서버는 AI 애플리케이션이 사용자의 Vault 파일에 직접 액세스할 수 있도록 허용하지 않습니다. [^3]

개인정보 보호 참고사항 : 이 플러그인과 함께 Claude Desktop을 사용하는 경우, Claude와의 대화는 기본적으로 Anthropic의 모델을 훈련하는 데 사용되지 않습니다. [^1]

특징

Claude Desktop과 같은 MCP 클라이언트에 연결하면 이 플러그인을 통해 다음이 가능합니다.

• Vault Access : AI 보조원이 Vault의 보안을 유지하면서 메모를 읽고 참조할 수 있도록 합니다. [^4]
• 의미 검색 : AI 도우미는 키워드뿐만 아니라 의미와 맥락을 기반으로 보관소를 검색할 수 있습니다. [^5]
• 템플릿 통합 : 동적 매개변수 및 콘텐츠 생성을 통해 AI 상호 작용을 통해 Obsidian 템플릿 실행 [^6]

모든 기능을 사용하려면 Claude Desktop과 같은 MCP 호환 클라이언트가 필요합니다. 이 플러그인은 이러한 통합을 지원하는 서버 구성 요소를 제공하기 때문입니다. 이 플러그인은 Obsidian의 기능을 직접 수정하는 대신, AI 애플리케이션이 볼트와 효과적으로 연동될 수 있도록 안전한 브리지를 생성합니다.

필수 조건

필수의

• Obsidian v1.7.7 이상
• Claude Desktop 설치 및 구성
• API 키로 로컬 REST API 플러그인이 설치 및 구성됨

추천

• 향상된 템플릿 기능을 위한 Templater 플러그인
• 의미 검색 기능을 위한 Smart Connections 플러그인

설치

[!중요] 이 플러그인을 사용하려면 컴퓨터에서 로컬로 실행되는 보안 서버 구성 요소가 필요합니다. 이 서버는 서명된 실행 파일로 배포되며, 전체 소스 코드는 packages/mcp-server/ 에서 확인할 수 있습니다. 보안 조치 및 코드 서명 프로세스에 대한 자세한 내용은 보안 섹션을 참조하세요.

1. Obsidian 커뮤니티 플러그인에서 플러그인을 설치하세요
2. Obsidian 설정에서 플러그인을 활성화하세요
3. 플러그인 설정을 엽니다
4. "서버 설치"를 클릭하여 MCP 서버를 다운로드하고 구성하세요.

설치 버튼을 클릭하면 다음이 수행됩니다.

• 플랫폼에 적합한 MCP 서버 바이너리를 다운로드하세요
• Claude Desktop을 구성하여 서버를 사용합니다.
• 필요한 권한 및 경로를 설정하세요

설치 위치

• 서버 바이너리 : {vault}/.obsidian/plugins/obsidian-mcp-tools/bin/
• 로그 파일 :
  • macOS: ~/Library/Logs/obsidian-mcp-tools
  • 윈도우: %APPDATA%\obsidian-mcp-tools\logs
  • 리눅스: ~/.local/share/obsidian-mcp-tools/logs

구성

플러그인 설정에서 "서버 설치" 버튼을 클릭하면 플러그인이 자동으로 다음을 수행합니다.

1. 적절한 MCP 서버 바이너리를 다운로드하세요
2. 로컬 REST API 플러그인의 API 키를 사용하세요
3. MCP 서버를 사용하도록 Claude Desktop 구성
4. 적절한 경로와 권한을 설정하세요

구성 프로세스는 자동화되어 있지만, 서버 바이너리를 설치하고 Claude Desktop 구성을 수정하려면 사용자의 명시적인 권한이 필요합니다. 이 초기 설정 단계 외에는 추가적인 수동 구성이 필요하지 않습니다.

문제 해결

문제가 발생하는 경우:

1. 플러그인 설정을 확인하여 다음을 확인하세요.
   • 필수 플러그인이 모두 설치되었습니다
   • 서버가 제대로 설치되었습니다
   • Claude Desktop이 구성되었습니다
2. 로그를 검토하세요:
   • 플러그인 설정 열기
   • 리소스 아래에서 "로그 열기"를 클릭하세요.
   • 오류 메시지나 경고가 있는지 확인하세요.
3. 일반적인 문제:
   • 서버가 시작되지 않습니다 . Claude Desktop이 실행 중인지 확인하세요.
   • 연결 오류 : 로컬 REST API 플러그인이 구성되었는지 확인하세요
   • 권한 오류 : 서버를 다시 설치해보세요

보안

이진 분포

• 모든 릴리스는 재현 가능한 빌드를 사용하여 GitHub Actions를 사용하여 빌드됩니다.
• 바이너리는 SLSA 출처를 사용하여 서명되고 증명됩니다.
• 릴리스 워크플로는 저장소에서 완전히 감사 가능합니다.

런타임 보안

• MCP 서버는 최소한의 필수 권한으로 실행됩니다.
• 모든 통신은 암호화됩니다
• API 키는 플랫폼별 자격 증명 저장소를 사용하여 안전하게 저장됩니다.

이진 검증

MCP 서버 바이너리는 SLSA 출처 증명 과 함께 게시됩니다. 이는 바이너리가 어디에서 어떻게 생성되었는지에 대한 암호화된 증거를 제공합니다. 이를 통해 다운로드하는 바이너리의 무결성과 출처를 보장할 수 있습니다.

GitHub CLI를 사용하여 바이너리를 확인하려면:

1. GitHub CLI 설치:지엑스피1
2. 이진을 확인하세요:
   gh attestation verify --owner jacksteamdev <binary path or URL>

검증 결과 다음이 표시됩니다.

• 바이너리의 SHA256 해시
• 이 저장소의 GitHub Actions 워크플로에 의해 빌드되었음을 확인했습니다.
• 이를 생성한 특정 워크플로 파일 및 버전 태그
• SLSA 레벨 3 빌드 요구 사항 준수

이 검증은 바이너리가 변조되지 않았고 이 저장소의 소스 코드에서 직접 빌드되었음을 보장합니다.

보안 문제 보고

보안 취약점은 보안 정책을 통해 신고해 주세요. 공개된 공간에서 보안 취약점을 신고하지 마세요.

개발

이 프로젝트는 기능 기반 아키텍처를 기반으로 하는 모노리포 구조를 사용합니다. 자세한 프로젝트 아키텍처 문서는 .clinerules 를 참조하세요.

클라인 사용

이 프로젝트의 일부 코드는 AI 코딩 에이전트인 Cline을 사용하여 구현되었습니다. Cline은 새로운 기능을 구현할 때 프로젝트 아키텍처와 패턴을 파악하기 위해 cline_docs/ 과 .clinerules 파일을 사용합니다.

작업 공간

이 프로젝트에서는 Bun 작업 공간 구조를 사용합니다.

건물

1. 종속성 설치:
   bun install
2. 모든 패키지를 빌드합니다.
   bun run build
3. 개발을 위해:
   bun run dev

요구 사항

• bun v1.1.42 이상
• 타입스크립트 5.0+

기여하다

1. 저장소를 포크하세요
2. 기능 브랜치 생성
3. 변경 사항을 만드세요
4. 테스트 실행:
   bun test
5. 풀 리퀘스트 제출

자세한 지침은 CONTRIBUTING.md를 참조하세요.

지원하다

• 버그 보고 및 기능 요청에 대한 이슈를 열어주세요.
• 질문과 일반적인 도움말에 대한 토론을 시작하세요

변경 사항

각 릴리스의 변경 사항 목록은 CHANGELOG.md를 참조하세요.

특허

MIT 라이센스

각주

[^1]: Claude 데이터 개인 정보 보호 및 보안에 대한 정보는 Claude AI의 데이터 사용 정책을 참조하세요. [^2]: 모델 컨텍스트 프로토콜에 대한 자세한 내용은 MCP 소개를 참조하세요. [^3]: 사용 가능한 MCP 클라이언트 목록은 MCP 예제 클라이언트를 참조하세요. [^4]: Obsidian 플러그인 로컬 REST API가 필요합니다. [^5]: Obsidian 플러그인 스마트 연결이 필요합니다. [^6]: Obsidian 플러그인 템플릿러가 필요합니다.