mcp-zettel

Claude(또는 모든 MCP 클라이언트)에 Zettelkasten 형태의 지속적인 메모리를 제공하세요.

MCP 서버는 Claude Desktop, Claude Code, Cursor 또는 모든 MCP 호환 클라이언트에 원자적이고 상호 연결된 마크다운 노트로 구성된 개인 지식 베이스를 노출합니다. 이 서버를 연결하면 어시스턴트가 노트를 생성하고, [[wiki-links]]를 사용하여 상호 참조하며, 키워드나 태그로 검색하고, 백링크를 탐색할 수 있습니다. 이를 통해 사용자가 직접 복사하여 붙여넣을 필요 없이 세션 전반에 걸쳐 지속 가능한 컨텍스트를 구축하고 활용할 수 있습니다.

왜 필요한가요?

LLM과 시작하는 모든 대화는 이전에 결정했거나 작성했거나 학습한 내용에 대한 컨텍스트가 전혀 없는 상태에서 시작됩니다. Zettelkasten 방식(작은 원자적 노트 + 노트 간의 명시적 링크)은 LLM이 접근 가능한 메모리에 매우 적합합니다. 청크가 자연스럽게 작고, 링크를 통해 관련성이 명확해지며, 저장 방식이 사용자 디스크의 일반 마크다운 파일이기 때문입니다.

이 MCP 서버는 MCP 도구를 통해 해당 지식 베이스를 모든 LLM 클라이언트에 노출하므로, 모델은 다음을 수행할 수 있습니다:

• 생성: 보관할 가치가 있는 결정이나 통찰을 공유할 때 새 노트를 생성합니다.

• 검색: 답변하기 전에 주제에 관한 노트를 검색합니다 ("X에 대해 무엇을 결정했지?").

• 연결: 노트를 양방향으로 연결하여 그래프를 구축합니다 ("이것은 [[a3f2c9]]와 모순됨").

• 백링크 탐색: 개념과 연결된 모든 항목을 찾습니다.

사용자는 디스크에 일반 마크다운 파일을 보관하고, 모델은 해당 파일에 구조화된 방식으로 접근합니다.

Related MCP server: obsidian-pkm

클라이언트에서의 모습

서버를 연결한 후, LLM은 다음과 같은 작업을 수행할 수 있습니다(클라이언트가 실제 도구 호출을 표시합니다):

> What did I conclude about RAG chunk sizes?
[searches notes with query "rag chunk size"]
[reads 2 matching notes]
Based on your notes a3f2c9 ("RAG chunk sizing") and b7e412 ("Sentence-boundary
splitting"), you concluded: 800 chars with ~15% overlap, sentence-aligned.
You flagged that pure character chunking ([[2f00a1]]) hurt recall on your
arxiv set and moved away from it.

노출된 MCP 도구

추가 MCP 리소스:

• zettel://all — 모든 노트의 한 줄 인덱스

• zettel://{note_id} — 전체 렌더링된 노트

• zettel://graph — v0.4. 모든 노트와 [[wiki-link]]를 포함한 Mermaid 다이어그램으로, 마크다운+Mermaid를 지원하는 모든 클라이언트(Claude Desktop, Obsidian, mdBook 등)에서 인라인으로 렌더링됩니다.

• zettel://graph/tag/{tag} — v0.4. 동일한 다이어그램이지만 {tag}가 포함된 노트와 그 직접적인 이웃으로 제한됩니다. 전체 그래프가 너무 복잡해질 때 유용합니다.

두 가지 검색 도구

키워드 검색은 용어를 정확히 알고 있을 때 유용합니다. 비용이 저렴하고 순위가 예측 가능하며, 정확히 일치하는 항목이 유사한 항목보다 항상 우선합니다. 의미론적 검색은 쿼리 문구가 노트 문구와 일치하지 않을 때 유용합니다. 예를 들어 노트에는 "throttling"이라고 되어 있는데 "rate limiting"으로 검색하거나, 노트는 "TTL tuning"에 관한 것인데 "why my cache is cold"라고 질문하는 경우입니다. LLM은 상황에 맞는 도구를 호출하며, 도구 설명에 각각의 용도가 명시되어 있습니다.

임베딩 모델은 기본적으로 BAAI/bge-small-en-v1.5(384-dim, ~130 MB, CPU 전용)를 사용합니다. MCP_ZETTEL_EMBEDDING_MODEL로 재정의할 수 있습니다. 인덱스는 쓰기 작업 후 첫 번째 의미론적 쿼리 시 지연 생성되므로 처음에는 약간의 대기 시간이 발생하지만, 그 이후에는 서버 프로세스가 실행되는 동안 메모리에 유지됩니다.

설치

git clone https://github.com/dhruvpatel1706/mcp-zettel.git
cd mcp-zettel
pip install -e .

Python 3.10 이상이 필요합니다.

연결 설정

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 운영체제에 해당하는 파일을 편집하고 다음을 추가합니다:

{
  "mcpServers": {
    "zettel": {
      "command": "mcp-zettel-server"
    }
  }
}

Claude Desktop을 재시작합니다. 이제 모델에서 zettel 도구를 사용할 수 있습니다.

Claude Code

claude mcp add zettel -- mcp-zettel-server

Cursor / Continue / 기타 stdio MCP 클라이언트

클라이언트에서 mcp-zettel-server를 명령어로 지정하세요. 서버는 stdio를 통해 MCP를 통신합니다.

사용자 지정 저장 위치

MCP_ZETTEL_ROOT를 설정하여 기본값인 ~/.mcp-zettel을 재정의할 수 있습니다:

{
  "mcpServers": {
    "zettel": {
      "command": "mcp-zettel-server",
      "env": { "MCP_ZETTEL_ROOT": "/Users/you/vault" }
    }
  }
}

CLI 직접 사용 (MCP 클라이언트 불필요)

동일한 저장소에 일반 CLI를 통해 접근할 수 있습니다. LLM 세션 외부에서 지식 베이스를 검사, 편집 또는 시드하려는 고급 사용자에게 유용합니다.

mcp-zettel create "RAG chunk sizing" \
  --body "Settled on 800 chars, 15% overlap, sentence-aligned. See [[b7e412]]." \
  --tag rag --tag decisions

mcp-zettel list --tag rag
mcp-zettel search "sentence boundary"
mcp-zettel show a3f2c9
mcp-zettel backlinks a3f2c9

디스크 레이아웃

~/.mcp-zettel/
└── notes/
    ├── a3f2c9.md          ← one markdown file per note
    ├── b7e412.md          ← YAML frontmatter: title, tags, created_at, updated_at
    └── ...                ← body is plain markdown; [[id]] is a wiki-link

모든 노트는 단일 파일입니다. 즉, 백업(git)이 쉽고, grep이 용이하며, 특정 도구에 종속되지 않습니다. 이 서버 사용을 중단하더라도 마크다운 파일 디렉토리는 그대로 유지됩니다.

설계 선택

• 데이터베이스가 아닌 파일 기반. 노트당 하나의 마크다운 파일이므로 어떤 편집기에서든 편집하고, git으로 백업하며, 별도의 도구 없이 검사할 수 있습니다.

• 슬러그화된 제목이 아닌 짧은 16진수 ID. [[a3f2c9]]는 안정적입니다. 제목을 변경해도 모든 인바운드 링크가 유지됩니다. 파일 이름 기반 슬러그보다 짧기도 합니다.

• 파생된 양방향 링크. 백링크는 모든 노트의 본문을 스캔하여 [[target_id]]를 찾는 방식으로 읽을 때 계산됩니다. 일관성을 유지해야 할 별도의 인덱스가 없습니다. 이 도구가 설계된 규모(수천 개 이하의 노트)에서는 매우 효율적입니다.

• 제목/태그 가중치 검색. 제목 일치는 3배, 태그 일치는 2배, 본문 일치는 1배의 가중치를 둡니다. 노트 제목에 "retrieval"이 언급된 경우가 본문 중간에 단어가 한 번 등장하는 경우보다 해당 주제와 더 관련이 있다는 직관과 일치합니다.

• 저수준 MCP가 아닌 FastMCP. MCP Python SDK의 데코레이터 기반 FastMCP 인터페이스를 사용하여 도구를 Pydantic 타입 인자가 있는 Python 함수로 정의하므로 수동으로 JSON 스키마를 작성할 필요가 없습니다.

개발

pip install -e ".[dev]"
pytest
black --check src tests
isort --check-only --profile black src tests
flake8 src tests --max-line-length=100 --ignore=E501,W503,E203

CI는 Python 3.10 / 3.11 / 3.12에서 실행됩니다.

MCP 인스펙터를 사용하여 서버를 대화형으로 검사하세요:

npx @modelcontextprotocol/inspector mcp-zettel-server

프롬프트 템플릿 (v0.3)

프롬프트 메뉴를 지원하는 MCP 클라이언트(Claude Desktop, Cursor)는 일반적인 Zettelkasten 작업을 수행하는 "올바른 방법"을 인코딩한 4개의 서버 측 템플릿을 제공하므로 지침을 다시 입력할 필요가 없습니다:

이들은 @mcp.prompt()로 등록된 문자열 반환 함수입니다. 문구를 서버 측에 유지하면 Claude Desktop, Claude Code, Cursor 어디에서 호출하든 동일한 "distill" 프롬프트가 일관되게 작동합니다.

로드맵

• [x] v0.2 — 키워드 검색과 함께 임베딩 기반 의미론적 검색 지원

• [x] v0.3 — 일반적인 노트 작업을 위한 @mcp.prompt() 템플릿

• [x] v0.4 — 링크의 Mermaid 다이어그램을 반환하는 그래프 뷰 리소스 (zettel://graph)

• [ ] v0.5 — 다중 장치 접근을 위한 원격 Streamable HTTP 전송

라이선스

MIT. LICENSE를 참조하세요.