mcp-zettel

Gib Claude (oder jedem beliebigen MCP-Client) persistenten Speicher in Form eines Zettelkastens.

Ein MCP-Server, der eine persönliche Wissensdatenbank aus atomaren, miteinander verknüpften Markdown-Notizen für Claude Desktop, Claude Code, Cursor oder jeden anderen MCP-kompatiblen Client bereitstellt. Schließe ihn an, und der Assistent kann Notizen erstellen, sie mit [[wiki-links]] kreuzverweisen, nach Schlüsselwörtern oder Tags suchen und Backlinks verfolgen – so kann er dauerhaften Kontext über Sitzungen hinweg aufbauen und nutzen, ohne dass du etwas kopieren und einfügen musst.

Warum

Jeder Chat, den du mit einem LLM beginnst, startet ohne Kontext darüber, was du bereits entschieden, geschrieben oder gelernt hast. Die Zettelkasten-Methode (kleine atomare Notizen + explizite Links zwischen ihnen) eignet sich hervorragend als LLM-zugänglicher Speicher: Die Einheiten sind von Natur aus klein, Links machen die Relevanz explizit und die Speicherung erfolgt als einfaches Markdown auf deiner eigenen Festplatte.

Dieser MCP-Server stellt diese Wissensdatenbank jedem LLM-Client über MCP-Tools zur Verfügung, sodass das Modell:

• Erstellen einer neuen Notiz, wenn du eine Entscheidung oder Erkenntnis teilst, die es wert ist, behalten zu werden

• Suchen nach Notizen zu einem Thema vor der Beantwortung („Was habe ich über X entschieden?“)

• Verknüpfen von Notizen in beide Richtungen, um einen Graphen aufzubauen („Dies widerspricht [[a3f2c9]]“)

• Verfolgen von Backlinks, um alles zu finden, was mit einem Konzept verbunden ist

Du behältst einfache Markdown-Dateien auf der Festplatte. Das Modell erhält strukturierten Zugriff darauf.

Related MCP server: obsidian-pkm

Wie es in einem Client aussieht

Nach dem Verbinden des Servers kann das LLM Dinge wie diese tun (dein Client zeigt die tatsächlichen Tool-Aufrufe an):

> 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.

Verfügbare MCP-Tools

Plus MCP-Ressourcen:

• zettel://all — einzeiliger Index jeder Notiz

• zettel://{note_id} — vollständig gerenderte Notiz

• zettel://graph — v0.4. Mermaid-Diagramm jeder Notiz + [[wiki-link]] im Tresor, inline gerendert von jedem Markdown+Mermaid-Client (Claude Desktop, Obsidian, mdBook…).

• zettel://graph/tag/{tag} — v0.4. Dasselbe Diagramm, aber beschränkt auf Notizen mit {tag} plus deren direkte Nachbarn – nützlich, sobald der vollständige Graph zu unübersichtlich wird.

Zwei Suchwerkzeuge, nicht eines

Die Stichwortsuche ist das, was du willst, wenn du den Begriff kennst. Sie ist kostengünstig, das Ranking ist vorhersehbar und exakte Übereinstimmungen schlagen immer ähnlich klingende. Die semantische Suche gewinnt, wenn der Wortlaut der Anfrage nicht mit dem Wortlaut der Notiz übereinstimmt – wenn man nach „Rate Limiting“ fragt, während die Notiz es „Throttling“ nennt, oder „warum mein Cache kalt ist“, wenn die Notiz von „TTL Tuning“ handelt. Das LLM kann aufrufen, was sinnvoll ist; die Tool-Beschreibungen sagen ihm, welches welches ist.

Das Einbettungsmodell ist standardmäßig BAAI/bge-small-en-v1.5 (384-dim, ~130 MB, nur CPU). Überschreibe dies mit MCP_ZETTEL_EMBEDDING_MODEL. Der Index wird bei der ersten semantischen Abfrage nach einem Schreibvorgang träge neu aufgebaut, daher gibt es beim ersten Mal eine kurze Wartezeit – danach bleibt er für die Lebensdauer des Serverprozesses im Speicher.

Installation

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

Python 3.10+.

Einrichten

Claude Desktop

Bearbeite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder das Äquivalent auf deinem Betriebssystem und füge hinzu:

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

Starte Claude Desktop neu. Die Zettel-Tools stehen dem Modell nun zur Verfügung.

Claude Code

claude mcp add zettel -- mcp-zettel-server

Cursor / Continue / jeder stdio MCP-Client

Verweise den Client auf mcp-zettel-server als Befehl; der Server spricht MCP über stdio.

Benutzerdefinierter Speicherort

Setze MCP_ZETTEL_ROOT, um das Standardverzeichnis ~/.mcp-zettel zu überschreiben:

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

CLI direkt verwenden (kein MCP-Client erforderlich)

Der gleiche Speicher ist über eine einfache CLI zugänglich – nützlich für Power-User, die die Wissensdatenbank außerhalb einer LLM-Sitzung inspizieren, bearbeiten oder befüllen möchten.

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

Layout auf der Festplatte

~/.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

Jede Notiz ist eine einzelne Datei. Das bedeutet: einfache Backups (git), einfaches Grep, kein Lock-in. Wenn du jemals aufhörst, diesen Server zu verwenden, hast du immer noch ein Verzeichnis mit Markdown-Dateien.

Design-Entscheidungen

• Dateien, keine Datenbank. Eine Notiz pro Markdown-Datei bedeutet, dass du sie in jedem Editor bearbeiten, mit git sichern und ohne Tools inspizieren kannst. Der Speicher ist nur ein dünner Kleber darüber.

• Kurze Hex-IDs, keine slugifizierten Titel. [[a3f2c9]] ist stabil – benenne den Titel um und alle eingehenden Links werden immer noch aufgelöst. Außerdem kürzer als ein dateinamenbasierter Slug.

• Bidirektionale Links abgeleitet, nicht gespeichert. Backlinks werden beim Lesen berechnet, indem der Textkörper jeder Notiz nach [[target_id]] durchsucht wird. Kein separater Index, der konsistent gehalten werden muss. Trivial in der Größenordnung, für die dies konzipiert ist (≤ niedrige Tausender an Notizen).

• Titel/Tag-gewichtete Suche. Titel-Treffer zählen 3×, Tag-Treffer 2×, Textkörper-Treffer 1×. Entspricht der Intuition, dass eine Notiz, deren Titel „Retrieval“ erwähnt, mehr über Retrieval aussagt als eine Notiz, die das Wort einmal mitten im Textkörper enthält.

• FastMCP, nicht Low-Level MCP. Die dekoratorbasierte FastMCP-Oberfläche des MCP Python SDK bedeutet, dass Tools einfach Python-Funktionen mit Pydantic-typisierten Argumenten sind – kein manuelles Erstellen von JSON-Schemas.

Entwicklung

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 läuft auf Python 3.10 / 3.11 / 3.12.

Inspiziere den Server interaktiv mit dem MCP-Inspektor:

npx @modelcontextprotocol/inspector mcp-zettel-server

Prompt-Vorlagen (v0.3)

MCP-Clients, die Prompt-Menüs unterstützen (Claude Desktop, Cursor), erhalten vier serverseitige Vorlagen, die den „richtigen Weg“ für gängige Zettelkasten-Aktionen kodieren, ohne dass du die Anweisungen erneut eingeben musst:

Dies sind nur String-zurückgebende Funktionen, die mit @mcp.prompt() registriert sind. Die serverseitige Formulierung bedeutet, dass sich derselbe „Distill“-Prompt konsistent verhält, egal ob du ihn von Claude Desktop, Claude Code oder Cursor aufrufst.

Roadmap

• [x] v0.2 — einbettungsbasierte semantische Suche neben der Stichwortsuche

• [x] v0.3 — @mcp.prompt() Vorlagen für gängige Notizoperationen

• [x] v0.4 — Graph-View-Ressource (zettel://graph), die ein Mermaid-Diagramm der Links zurückgibt

• [ ] v0.5 — Remote Streamable HTTP-Transport für geräteübergreifenden Zugriff

Lizenz

MIT. Siehe LICENSE.