obsidian-mcp-server

Obsidian 학습 볼트용 MCP 서버(Model Context Protocol)입니다. Claude에게 노트 검색, 노트 내용, Decks 형식의 플래시카드 생성, Lerntracker 플러그인의 학습 계획 수립에 대한 접근 권한을 제공합니다.

Python, MCP SDK 2.x, stdio 전송 방식.

목적

지금까지 로직은 두 개의 Obsidian 플러그인에서 실행되었습니다:

• Decks(타사 플러그인)는 플래시카드를 렌더링하지만 생성하지는 않습니다 — 카드는 손으로 작성되었습니다.

• Lerntracker(자체 플러그인)는 학습 진행 상황과 학습 계획을 관리하지만, 학습 내용을 의도적으로 날짜에 자동 배분하지는 않습니다.

이 서버는 두 가지 빈틈을 모두 메웁니다: Claude는 기존 파일 형식으로 카드를 직접 만들고, Lerntracker의 data.json에 다시 기록되는 학습 계획을 계산할 수 있습니다.

Related MCP server: Nexus MCP for Obsidian

설치

cd ~/Projects/obsidian-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

구성

두 경로 모두 환경 변수에서 가져옵니다 — 하드코딩된 것은 없습니다.

볼트 경로의 기본값은 iCloud 동기화된 Obsidian에 적합합니다; 다른 설정이라면 OBSIDIAN_VAULT_PATH를 설정하기만 하면 됩니다.

Lerntracker 경로는 Obsidian 볼트가 중첩될 수 있으므로 별도로 설정할 수 있습니다: 하위 폴더에 다른 볼트가 있으면 그 볼트는 자체 data.json을 갖습니다. 기본값은 메인 볼트의 것을 가리킵니다.

도구

모든 스키마는 SDK가 Type Hints와 Docstrings에서 생성합니다 — 코드에는 손으로 작성한 JSON 스키마가 없습니다.

플래시카드 형식

create_flashcard는 볼트의 기존 카드가 사용하는 정확한 형식(헤더 문단)을 쓰며, 출처에 대한 위키링크가 추가됩니다:

---
tags: [decks]
---

## Was ist ein Signal?

Eine zeitabhängige, messbare physikalische Größe.

Quelle: [[01_Physikalische_Schicht]]

대상 파일은 원본 노트의 강의 폴더에서 결정됩니다; deck은 파일 이름을 재정의합니다. 파일이 없으면 tags: [decks]로 생성됩니다. 앞면이 동일한 카드는 중복 생성되지 않고 건너뜁니다.

Decks의 학습 상태는 Markdown 파일이 아닌 SQLite 데이터베이스에 있습니다. 서버는 이를 건드리지 않습니다 — FSRS 기록은 그대로 유지됩니다.

generate_summary가 직접 요약하지 않는 이유

서버에는 언어 모델이 없습니다. 서버는 노트를 구조적으로 반환하고(개요, 지표, 전체 텍스트), 요약은 클라이언트 측, 즉 Claude Desktop의 모델이 작성합니다. 이후 save_summary로 저장됩니다. 이것은 일반적인 MCP 역할 분담입니다: 서버는 맥락을 제공하고 작업을 실행하며, 모델이 글을 작성합니다.

서버가 대신 직접 요약하려면 Anthropic API를 호출하고 자체 API 키가 필요합니다.

학습 계획 로직

generate_study_plan은 각 열린 하위 주제를 구체적인 날짜에 배분합니다:

1. 강의는 시험 날짜순으로 정렬됩니다 — 가장 빠른 시험이 먼저입니다.

2. 학습 마감 = examDate − bufferDays; 버퍼 일수는 복습을 위해 비워 둡니다.

3. 학습일은 settings.weeklyHours에서 가져옵니다(0 = 일요일 … 6 = 토요일). 0시간인 날과 모든 blockedDates는 건너뜁니다.

4. 각 하위 주제는 hours_per_subtopic(기본 1.5시간)이 소요되며 잔여 용량이 있는 가장 이른 날에 배치됩니다. 하루에 맞지 않으면 여러 날로 분할됩니다 — 플러그인은 여러 dates를 지원합니다.

5. 이미 완료 처리된 하위 주제와 dates가 이미 있는 하위 주제는 그대로 둡니다.

6. 학습 마감 전에 더 이상 들어갈 수 없는 것은 조용히 버려지지 않고 경고로 보고됩니다.

모든 쓰기 작업 전에 파일 옆에 백업이 생성됩니다(data.backup-<Zeitstempel>.json); 임시 파일을 통해 원자적으로 기록됩니다. dry_run=True는 계획만 표시합니다.

작성 후 Obsidian에서 Cmd+R을 눌러 플러그인이 다시 로드되도록 하세요.

리소스

템플릿은 의도적으로 {path} 대신 {+path}(Reserved Expansion)를 사용합니다. 일반 템플릿 변수는 슬래시를 매칭하지 않습니다 — {path}를 사용하면 하위 폴더의 모든 노트가 조용히 찾아지지 않으며, 볼트에서는 사실상 모든 노트가 강의 폴더에 있습니다.

MCP Inspector로 로컬 테스트

MCP Inspector는 SDK의 CLI를 통해 시작되며, 도구와 리소스를 개별적으로 호출할 수 있는 웹 인터페이스를 엽니다. 실행하려면 npx(Node.js)와 uv가 필요합니다.

source .venv/bin/activate && mcp dev main.py

명령은 http://localhost:6274와 같은 URL을 출력합니다(세션 토큰이 추가됨). 브라우저에서 열고 왼쪽의 Connect를 클릭한 다음:

• Tools 탭 → List Tools → 도구 선택, 인수 입력, Run Tool

• Resources 탭 → List Resources → vault://structure 클릭

• 템플릿 리소스의 경우 note://<Kursordner>/Flashcards/<Datei>.md 패턴에 따라 URI를 직접 입력합니다

다른 볼트를 사용하는 경우:

OBSIDIAN_VAULT_PATH="$HOME/Pfad/zu/deinem/Vault" mcp dev main.py

쓰기 도구를 시험해 보려면 임시 볼트가 유용합니다:

OBSIDIAN_VAULT_PATH=/tmp/testvault mcp dev main.py

Claude Desktop 연동

구성 파일: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "/Users/DEIN_NAME/Projects/obsidian-mcp-server/.venv/bin/python",
      "args": ["/Users/DEIN_NAME/Projects/obsidian-mcp-server/main.py"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/Users/DEIN_NAME/Pfad/zu/deinem/Vault"
      }
    }
  }
}

중요: 절대 경로를 사용하세요 — ~와 $HOME은 여기서 확장되지 않습니다. command로 venv의 Python을 지정하세요: Claude Desktop은 활성화된 환경 없이 서버를 시작하므로, 단순한 "python3"는 mcp 패키지를 찾지 못합니다.

파일이 이미 존재하면 기존 mcpServers 객체에 "obsidian-vault" 항목만 삽입하세요. 그런 다음 Claude Desktop을 완전히 종료하고 다시 시작하면 서버가 입력 필드의 도구 메뉴에 나타납니다.

보안

도구 또는 리소스 호출의 모든 경로는 볼트를 기준으로 검증됩니다: 절대 경로와 .. 트래버설은 거부되며, 해석된 대상은 OBSIDIAN_VAULT_PATH 내에 있어야 합니다. .obsidian, .git, .trash, .claude, node_modules는 검색 및 구조 목록에서 제외됩니다 — 그렇지 않으면 플러그인 번들이 결과를 가득 채울 것입니다.

save_summary는 기존 파일을 덮어쓰지 않고, create_flashcard는 중복 카드를 만들지 않으며, generate_study_plan은 쓰기 전에 data.json을 백업합니다.

테스트

Python 3.14에서 mcp 2.0.0을 대상으로: 도구 스키마, 리소스 템플릿, 실제 ClientSession과의 stdio 핸드셰이크, 경로 가드, 그리고 임시 볼트에 대한 쓰기 도구(여러 날 분할, 차단된 날짜, 0시간 요일, 오버플로 케이스 포함).

라이선스

MIT — LICENSE 참조.