cyanheads/obsidian-mcp-server

Read, write, search, and surgically edit Obsidian vault notes, tags, and frontmatter via MCP. STDIO or Streamable HTTP.

개요

obsidian‑mcp‑server는 AI 에이전트(또는 MCP 호환 클라이언트)가 Obsidian 볼트에 저장된 노트를 읽고 편집할 수 있게 하는 브리지입니다. Obsidian Local REST API 플러그인과 통신하며, 간단한 stdio 인터페이스 또는 경량 HTTP 서버를 통해 MCP 도구 및 리소스 URL 집합을 노출합니다. 서버는 인증, 폴더 범위 권한, 그리고 다음과 같은 풍부한 작업을 처리합니다:

노트 가져오기(전체 내용, 단일 제목 또는 파싱된 문서 맵)
노트, 태그 또는 명령 팔레트 항목 나열
일반 텍스트, JSONLogic 또는 BM25(Omnisearch 플러그인을 통해)로 노트 검색
섹션, 블록, 프론트매터 생성, 추가, 패치 또는 교체
태그 및 프론트매터 키 관리
노트 삭제(선택적 사용자 확인) 및 Obsidian UI에서 노트 열기.

모든 응답은 JSON-RPC 스타일 객체로, 상세한 오류 코드와 복구 힌트를 포함하여 자율 에이전트가 쉽게 소비하고 조치를 취할 수 있습니다.

주요 기능

기능	설명
MCP 기반 API	Model Context Protocol(MCP)을 구현하여 모든 MCP 클라이언트(Claude Desktop, Cursor, VS Code, 사용자 정의 봇)가 stdio 또는 HTTP를 통해 도구를 호출할 수 있습니다.
세분화된 권한	폴더 범위 읽기/쓰기 정책, 읽기 전용 모드, 선택적 JWT/OAuth 인증으로 볼트를 보호합니다.
풍부한 노트 조작	전체 파일 쓰기, 단일 제목, 블록 또는 프론트매터 필드 교체, 정규식 기반 검색-교체 수행.
태그 및 프론트매터 관리	태그(프론트매터, 인라인 또는 둘 다) 추가/제거/나열 및 임의 프론트매터 키 가져오기/설정/삭제.
검색 유연성	텍스트 검색, JSONLogic 쿼리 또는 BM25 순위 Omnisearch(Omnisearch 플러그인이 있는 경우).
에이전트 친화적 출력	오류에는 `reason`, JSON-RPC 코드, `recovery.hint`가 포함됩니다. 변경 도구는 크기 차이와 모호성 데이터를 보고합니다.
플러그 가능한 스토리지 및 로깅	인메모리, 파일 시스템, Supabase, Cloudflare KV/R2/D1 백엔드; 구조화된 로깅, 선택적 OpenTelemetry 추적.
다중 배포 옵션	Bun, Node(`npx`), Docker 또는 Streamable HTTP 서버로 실행.

일반적인 사용 사례 흐름

설정 – Obsidian Local REST API 플러그인을 설치하고, API 키를 생성하고, OBSIDIAN_API_KEY(선택적으로 OBSIDIAN_BASE_URL)를 설정합니다.
서버 시작 – HTTP 엔드포인트는 bun run start:http, stdio는 bunx obsidian-mcp-server@latest를 사용합니다.
도구 호출 – MCP 호환 클라이언트가 JSON-RPC 요청을 보냅니다. 예: obsidian_get_note로 노트 가져오기, obsidian_append_to_note로 글머리 기호 추가, obsidian_search_notes로 관련 콘텐츠 검색.
응답 처리 – 클라이언트는 구조화된 결과를 읽고, 오류의 recovery.hint를 확인하고, 후속 호출(예: obsidian_delete_note로 삭제 확인)을 발행할 수 있습니다.
반복 – 에이전트는 도구를 연결하여 볼트 내에서 지식을 자율적으로 구축, 편집, 구성할 수 있습니다.

설치 및 빠른 시작

# 클론 및 설치(Bun 권장)
git clone https://github.com/cyanheads/obsidian-mcp-server.git
cd obsidian-mcp-server
bun install

# 환경 템플릿 복사 및 API 키 추가
cp .env.example .env
# .env 편집 → OBSIDIAN_API_KEY=당신의 키 설정

# stdio(Bun) 또는 Docker로 실행
bunx obsidian-mcp-server@latest   # stdio
# 또는
docker run -i --rm -e OBSIDIAN_API_KEY=… ghcr.io/cyanheads/obsidian-mcp-server:latest

HTTP의 경우:

MCP_TRANSPORT_TYPE=http OBSIDIAN_API_KEY=… bun run start:http
# 서버는 http://127.0.0.1:3010/mcp 에서 실행

누가 이것을 사용할까요?

AI 에이전트 – Obsidian에 저장된 개인 지식 기반을 읽고 써야 하는 경우.
자동화 스크립트 – 대량 노트 업데이트, 태그 정리 또는 주기적 노트 생성을 위한.
개발자 도구 – 표준 프로토콜을 통해 Obsidian 볼트를 외부 IDE 또는 CLI 유틸리티에 노출하려는 경우.
연구 파이프라인 – Obsidian 볼트를 구조화된 데이터 저장소로 취급하고 프로그래밍 방식 액세스가 필요한 경우.

제한 사항 및 주의 사항

Obsidian Local REST API 플러그인에 의존합니다. 이 플러그인 없이는 서버가 작동할 수 없습니다.
일부 작업(예: Windows CRLF 파일의 제목 쓰기)은 이전 플러그인 버전에서 알려진 문제가 있습니다.
노트 삭제는 API 수준에서 되돌릴 수 없습니다. Obsidian의 로컬 휴지통만 복구할 수 있습니다.
서버는 자체 검색 엔진을 제공하지 않습니다 – Omnisearch 플러그인이 설치된 경우 해당 플러그인으로 전달합니다.
권한은 폴더 수준에서 적용됩니다. 잘못 구성된 OBSIDIAN_READ_PATHS/OBSIDIAN_WRITE_PATHS는 의도치 않게 액세스를 차단할 수 있습니다.

라이선스

Apache 2.0 – 무료로 사용, 수정, 배포할 수 있습니다.