Zettelkasten 지식 관리 방법론을 구현하는 Model Context Protocol (MCP) 서버로, Claude 및 기타 MCP 호환 클라이언트를 통해 원자적 노트 (atomic notes)를 생성, 연결, 탐색 및 합성할 수 있게 해줍니다.

Zettelkasten 방법론은 독일의 사회학자 Niklas Luhmann이 개발한 지식 관리 시스템으로, 그는 이를 통해 70권 이상의 저서와 수백 편의 논문을 집필했습니다. 이 방법론은 세 가지 핵심 원칙으로 구성됩니다:

원자성 (Atomicity): 각 노트는 정확히 하나의 아이디어만을 포함하며, 이를 통해 지식의 개별 단위가 됩니다.
연결성 (Connectivity): 노트들은 서로 연결되어 지식 네트워크를 형성하며, 아이디어 간의 의미 있는 관계를 구축합니다.
창발성 (Emergence): 네트워크가 성장함에 따라, 개별 노트를 생성했을 당시에는 명확하지 않았던 새로운 패턴과 통찰이 나타납니다.

Zettelkasten 접근 방식이 강력한 이유는 다음과 같이 다양한 방식으로 탐색을 가능하게 하기 때문입니다:

수직적 탐색 (Vertical exploration): 특정 주제 영역 내의 연결을 따라가며 특정 주제를 더 깊이 파고듭니다.
수평적 탐색 (Horizontal exploration): 도메인을 가로지르는 링크를 탐색함으로써 서로 다른 분야 간의 예상치 못한 관계를 발견합니다.

이러한 구조는 고유 식별자를 통해 각 정보에 쉽게 접근할 수 있는 동시에, 노트를 따라 사고의 흐름을 추적하며 뜻밖의 발견(serendipitous discoveries)을 유도합니다. Luhmann은 자신의 시스템을 "제2의 뇌" 또는 "대화 상대"라고 불렀으며, 이 디지털 구현체는 현대 기술을 통해 유사한 이점을 제공하는 것을 목표로 합니다.

• 타임스탬프 기반의 고유 ID를 사용하여 원자적 노트 생성

• 지식 그래프를 구축하기 위해 노트 간 양방향 연결

• 범주별 조직화를 위한 노트 태깅

• 내용, 태그 또는 링크를 통한 노트 검색

• 가독성 및 편집을 위한 마크다운 (markdown) 형식 사용

• AI 보조 지식 관리를 위해 MCP를 통해 Claude와 통합

• 이중 저장 아키텍처 (Dual storage architecture) (아래 참조)

• 단순화된 아키텍처를 위한 동기식 운영 모델 (Synchronous operation model)

• 지식 생성: Zettelkasten 방법론 자체에 관한 작은 Zettelkasten 지식 네트워크

Zettelkasten MCP 서버는 다음과 같은 다양한 유형의 노트를 지원합니다:

유형	핸들 (Handle)	설명
임시 노트 (Fleeting notes)	fleeting	아이디어를 포착하기 위한 빠르고 일시적인 노트
문헌 노트 (Literature notes)	literature	읽은 자료로부터 작성된 노트
영구 노트 (Permanent notes)	permanent	잘 정립된, 에버그린 (evergreen) 노트
구조 노트 (Structure notes)	structure	다른 노트들을 조직화하는 인덱스 또는 개요 노트
허브 노트 (Hub notes)	hub	주요 주제에 대한 Zettelkasten의 진입점

Zettelkasten MCP 서버는 노트 사이에 의미 있는 연결을 생성하는 포괄적인 시맨틱 연결 (semantic linking) 시스템을 사용합니다. 각 연결 유형은 특정 관계를 나타내며, 이를 통해 풍부하고 다차원적인 지식 그래프 (knowledge graph)를 형성할 수 있습니다.

주요 연결 유형 (Primary Link Type)	역방향 연결 유형 (Inverse Link Type)	관계 설명
reference	reference	관련 정보에 대한 단순 참조 (대칭 관계)
extends	extended_by	한 노트가 다른 노트의 개념을 기반으로 구축하거나 발전시킴
refines	refined_by	한 노트가 다른 노트를 명확하게 하거나 개선함
contradicts	contradicted_by	한 노트가 다른 노트와 상충하는 견해를 제시함
questions	questioned_by	한 노트가 다른 노트에 대해 질문을 제기함
supports	supported_by	한 노트가 다른 노트에 대한 증거를 제공함
related	related	일반적인 관계 (대칭 관계)

최대 효과를 보장하기 위해, LLM에게 정보를 처리하도록 요청하거나 Zettelkasten 노트를 탐색 또는 합성하도록 요청할 때 시스템 프롬프트 ("프로젝트 지침"), 프로젝트 지식, 그리고 적절한 채팅 프롬프트를 사용할 것을 권장합니다. 이 저장소의 docs 디렉토리에는 시작하는 데 필요한 파일들이 포함되어 있습니다:

하나를 선택하세요:

최종 사용자용:

• zettelkasten-methodology-technical.md

• link-types-in-zettelkasten-mcp-server.md

• (귀하의 프로젝트와 관련된 추가 정보)

• chat-prompt-knowledge-creation.md

• chat-prompt-knowledge-creation-batch.md

• chat-prompt-knowledge-exploration.md

• chat-prompt-knowledge-synthesis.md

개발자 및 기여자 안내:

참고: 선택 사항으로 repomix와 같은 도구를 사용하여 소스 코드를 포함할 수 있습니다.

이 시스템은 이중 저장 방식 (dual storage approach)을 사용합니다:

Markdown 파일 (Markdown Files): 모든 노트는 메타데이터를 위한 YAML 프론트매터 (YAML frontmatter)가 포함된, 사람이 읽을 수 있는 Markdown 파일로 저장됩니다. 이 파일들은 **신뢰할 수 있는 단일 원천 (source of truth)**이며 다음과 같은 작업이 가능합니다:

• 모든 텍스트 에디터에서 직접 편집

• 버전 관리 시스템 (Git 등) 아래 배치

• 표준 파일 백업 절차를 통한 백업

• 다른 텍스트 파일과 마찬가지로 공유 또는 전송

SQLite 데이터베이스 (SQLite Database): 다음과 같은 인덱싱 계층 (indexing layer) 역할을 합니다:

• 효율적인 쿼리 (querying) 및 검색 작업 촉진
• Claude가 지식 그래프 (knowledge graph)를 빠르게 탐색할 수 있도록 지원
• 더 빠른 링크 탐색을 위한 관계 정보 유지
• 필요 시 Markdown 파일로부터 자동으로 재구축

시스템 외부에서 Markdown 파일을 직접 편집하는 경우, 데이터베이스를 업데이트하기 위해 zk_rebuild_index 도구를 실행해야 합니다. 데이터베이스 자체는 언제든지 삭제할 수 있으며, Markdown 파일로부터 다시 생성됩니다.

# 저장소 복제 (Clone the repository)
git clone https://github.com/entanglr/zettelkasten-mcp.git
cd zettelkasten-mcp
...

예시 파일을 복사하여 프로젝트 루트에 .env 파일을 생성하세요:

cp .env.example .env

그런 다음 파일을 편집하여 연결 파라미터 (connection parameters)를 설정하세요.

python -m zettelkasten_mcp.main

또는 명시적인 설정을 사용하여 실행할 수 있습니다:

python -m zettelkasten_mcp.main --notes-dir ./data/notes --database-path ./data/db/zettelkasten.db

Claude Desktop에 다음 설정을 추가하세요:

{
"mcpServers": {
"zettelkasten": {
...

모든 도구는 더 나은 조직화를 위해 zk_ 접두사가 붙어 있습니다:

도구 (Tool)	설명 (Description)
zk_create_note	제목, 내용 및 선택적 태그를 포함한 새 노트 생성
zk_get_note	ID 또는 제목으로 특정 노트 검색
zk_update_note	기존 노트의 내용 또는 메타데이터 (metadata) 업데이트
zk_delete_note	노트 삭제
zk_create_link	노트 간의 링크 생성
zk_remove_link	노트 간의 링크 제거
zk_search_notes	내용, 태그 또는 링크로 노트 검색
zk_get_linked_notes	특정 노트에 연결된 노트 찾기
zk_get_all_tags	시스템 내의 모든 태그 목록 표시
zk_find_similar_notes	주어진 노트와 유사한 노트 찾기
zk_find_central_notes	연결이 가장 많은 노트 찾기
zk_find_orphaned_notes	연결이 없는 노트(고립된 노트) 찾기
zk_list_notes_by_date	생성/업데이트 날짜별로 노트 목록 표시
zk_rebuild_index	Markdown 파일로부터 데이터베이스 인덱스 (index) 재구축

zettelkasten-mcp/
├── src/
│ └── zettelkasten_mcp/
...

모델 (models)부터 MCP 서버 구현에 이르기까지 애플리케이션의 모든 계층을 다루는 Zettelkasten MCP를 위한 포괄적인 테스트 스위트 (test suite)입니다.

프로젝트 루트 디렉토리에서 다음을 실행하세요:

python -m pytest -v tests/

uv run pytest -v tests/

uv run pytest --cov=zettelkasten_mcp --cov-report=term-missing tests/

uv run pytest -v tests/test_models.py

uv run pytest -v tests/test_models.py::TestNoteModel

uv run pytest -v tests/test_models.py::TestNoteModel::test_note_validation

tests/
├── conftest.py - 모든 테스트를 위한 공통 픽스처 (fixtures)
├── test_integration.py - 전체 시스템에 대한 통합 테스트 (integration tests)
...

** ⚠️ 위험 부담은 사용자 본인에게 있습니다**: 이 소프트웨어는 실험적이며 어떠한 종류의 보증 없이 있는 그대로 제공됩니다. 데이터 무결성 (data integrity)을 보장하기 위한 노력이 이루어졌으나, 잠재적으로 데이터 손실이나 손상을 초래할 수 있는 버그가 포함되어 있을 수 있습니다. 항상 정기적으로 노트를 백업하고 중요한 정보를 사용하여 테스트할 때는 주의를 기울이십시오.

이 MCP 서버는 Claude의 도움을 받아 제작되었으며, Claude는 이 프로젝트의 원자적 사고(atomic thoughts)를 일관된 지식 그래프 (knowledge graph)로 구성하는 데 도움을 주었습니다. 훌륭한 제텔카스텐 (Zettelkasten) 시스템과 마찬가지로, Claude는 자칫 고립되어 남아있을 수 있었던 아이디어들 사이의 점들을 연결해 주었습니다. 하지만 루만 (Luhmann)의 종이 기반 시스템과 달리, Claude는 효과를 발휘하기 위해 90,000장의 인덱스 카드 (index cards)를 필요로 하지 않았습니다.

MIT License