CherryTree MCP Server

MCP server that exposes reading and writing of CherryTree .ctd (XML) files as native Claude Code tools.

Supports rich text, codeboxes, tables, images, anchors, and bookmarks. All writes go through automatic byte-by-byte auditing comparing the backup with the resulting file on disk.

Available Tools

Reading

• list_nodes — list tree nodes (with depth and breadcrumb)

• read_node — read a node's content (text, formatting, widgets)

• search_nodes — full-text search across all nodes

• list_bookmarks — list nodes marked as favorites

Writing

• create_node — create node (plain text or rich XML via content_xml)

• create_node_with_codebox — create node with codebox (or rich XML via content_xml)

• update_node_content — replace or append (plain text or rich XML via content_xml)

• append_codebox_to_node — add codebox or rich XML to an existing node

• update_node_properties — change name, tags, icon, color, readonly

• delete_node — delete node and children

• move_node — move node to another parent

Bookmarks

• add_bookmark — add node to favorites

• remove_bookmark — remove node from favorites

Related MCP server: notion-full-mcp

Rich Text (content_xml)

The writing tools accept content_xml for full CherryTree formatting:

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

Supported attributes in <rich_text>

Widgets (positioned by char_offset)

Widgets are rendered inline at the char_offset position (character count in the concatenated text of the <rich_text> elements). Each widget occupies exactly 1 character in the buffer.

<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"/>

Architecture

• Reads use lxml for XML parsing/queries (safe, no write-back)

• Writes use raw string manipulation to avoid \r normalization that corrupts char_offset in unedited nodes (lxml/ET serialization bug)

• Backup .ctd.bak created automatically before each write

• Audit byte-by-byte after each write: reads backup and new file from disk, compares prefix/suffix, identifies changed node, counts total nodes, validates XML

Audit format

Every write operation returns a report like:

[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

If any byte outside the target region differs between backup and disk, the report displays CORRUPTED! and INTEGRITY FAILURE.

Installation

1. Create virtualenv and install dependencies

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

2. Configure MCP in Claude Code

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. Restart Claude Code

The tools appear automatically as mcp__cherrytree__<tool_name>.

Environment variables

Requirements

• Python >= 3.11

• CherryTree v1.x (.ctd XML format, not .ctb SQLite)

• Dependencies: mcp[cli]>=1.0.0, lxml>=5.0.0

Limitations

• Only .ctd (XML) format. .ctb (SQLite) files are not supported.

• CherryTree needs to be reloaded (close/open or switch nodes) after MCP edits to reflect changes in the UI.

• Write operations with append=False in update_node_content replace the entire node content (text, codeboxes, images, tables).