CherryTree MCP Server

MCP-Server, der das Lesen und Schreiben von CherryTree-.ctd-Dateien (XML) als native Claude-Code-Tools bereitstellt.

Unterstützt Rich Text, Codeboxen, Tabellen, Bilder, Anker und Lesezeichen. Alle Schreibvorgänge durchlaufen eine automatische Byte-für-Byte-Prüfung, die das Backup mit der resultierenden Datei auf der Festplatte vergleicht.

Verfügbare Tools

Lesen

• list_nodes — Knoten des Baums auflisten (mit Tiefe und Breadcrumb)

• read_node — Inhalt eines Knotens lesen (Text, Formatierung, Widgets)

• search_nodes — Volltextsuche in allen Knoten

• list_bookmarks — als Favoriten markierte Knoten auflisten

Schreiben

• create_node — Knoten erstellen (Klartext oder Rich-XML über content_xml)

• create_node_with_codebox — Knoten mit Codebox erstellen (oder Rich-XML über content_xml)

• update_node_content — ersetzen oder anhängen (Klartext oder Rich-XML über content_xml)

• append_codebox_to_node — Codebox oder Rich-XML zu vorhandenem Knoten hinzufügen

• update_node_properties — Name, Tags, Symbol, Farbe, Schreibschutz ändern

• delete_node — Knoten und Unterknoten löschen

• move_node — Knoten zu anderem übergeordneten Knoten verschieben

Lesezeichen

• add_bookmark — Knoten zu den Favoriten hinzufügen

• remove_bookmark — Knoten aus den Favoriten entfernen

Related MCP server: notion-full-mcp

Rich Text (content_xml)

Die Schreib-Tools akzeptieren content_xml für die vollständige CherryTree-Formatierung:

<rich_text scale="h1" foreground="#00000000ffff" weight="heavy">Título</rich_text>
<rich_text>
Texto normal com </rich_text>
<rich_text weight="heavy">negrito</rich_text>
<rich_text> e </rich_text>
<rich_text style="italic">itálico</rich_text>
<rich_text foreground="#e66100" weight="heavy"> e laranja bold</rich_text>
<rich_text link="node 42">link interno</rich_text>

Unterstützte Attribute in <rich_text>

Widgets (positioniert über char_offset)

Widgets werden inline an der Position char_offset gerendert (Zeichenanzahl im verketteten Text der <rich_text>-Elemente). Jedes Widget belegt genau 1 Zeichen im Puffer.

<codebox char_offset="42" justification="left" frame_width="700"
         frame_height="200" width_in_pixels="1"
         syntax_highlighting="python3" highlight_brackets="1"
         show_line_numbers="0">print("hello")</codebox>

<table char_offset="100" col_min="40" col_max="400"
       col_widths="200,200" is_light="0">
  <row><cell>valor1</cell><cell>valor2</cell></row>
  <row><cell>header1</cell><cell>header2</cell></row>
</table>

<encoded_png char_offset="50" anchor="nome_ancora"/>

Architektur

• Lesezugriffe verwenden lxml für XML-Parsing/-Abfragen (sicher, ohne Zurückschreiben)

• Schreibzugriffe verwenden Roh-String-Manipulation, um eine \r-Normalisierung zu vermeiden, die char_offset in nicht bearbeiteten Knoten beschädigt (Fehler von lxml/ET beim Serialisieren)

• Backup .ctd.bak wird vor jedem Schreibvorgang automatisch erstellt

• Prüfung Byte-für-Byte nach jedem Schreibvorgang: liest Backup und neue Datei von der Festplatte, vergleicht Präfix/Suffix, identifiziert geänderten Knoten, zählt Gesamtzahl der Knoten, validiert XML

Prüfungsformat

Jeder Schreibvorgang gibt einen Bericht wie folgt zurück:

[AUDIT] readback 45,120,109 bytes: OK
  delta: +252 bytes (45,119,857 -> 45,120,109)
  change region: bak[45,119,844:45,119,844] -> disk[45,119,844:45,120,096]
  prefix (45,119,844 bytes): OK
  suffix (13 bytes): OK
  nodes: 5304 (backup) -> 5305 (disco) [+1]
  node adicionado: 6481 "Nome do Node" (alvo)
  integridade: OK
  XML parse: OK

Wenn sich ein einziges Byte außerhalb des Zielbereichs zwischen Backup und Festplatte unterscheidet, zeigt der Bericht CORRUPTED! und INTEGRITY FAILURE an.

Installation

1. Virtuelle Umgebung erstellen und Abhängigkeiten installieren

cd ~/cherrytree-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

2. MCP in Claude Code konfigurieren

claude mcp add cherrytree -s user \
  -e CHERRYTREE_FILE="/caminho/para/seu/arquivo.ctd" \
  -- /caminho/para/cherrytree-mcp/.venv/bin/python \
     /caminho/para/cherrytree-mcp/server.py

3. Claude Code neu starten

Die Tools erscheinen automatisch als mcp__cherrytree__<tool_name>.

Umgebungsvariablen

Voraussetzungen

• Python >= 3.11

• CherryTree v1.x (.ctd-XML-Format, nicht .ctb SQLite)

• Abhängigkeiten: mcp[cli]>=1.0.0, lxml>=5.0.0

Einschränkungen

• Nur .ctd-Format (XML). .ctb-Dateien (SQLite) werden nicht unterstützt.

• CherryTree muss nach Bearbeitungen über MCP neu geladen werden (schließen/öffnen oder Knoten wechseln), damit die Änderungen in der Benutzeroberfläche angezeigt werden.

• Schreibvorgänge mit append=False in update_node_content ersetzen den gesamten Inhalt des Knotens (Text, Codeboxen, Bilder, Tabellen).