Skip to main content
Glama
CherryTree MCP Server

CherryTree MCP Server

by lucaszarzur

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

Attribute

Values

Example

weight

heavy

bold

foreground

#RRRRGGGGBBBB (48-bit GTK)

#00000000ffff (blue)

background

#RRRRGGGGBBBB

highlight

style

italic

italic

underline

single

underlined

strikethrough

true

strikethrough

scale

h1-h6, small, sup, sub

headings

family

monospace

monospaced

justification

left, center, right, fill

alignment

link

webs URL, node UID, file BASE64, fold BASE64

links

indent

1-3

indentation

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

Variable

Description

CHERRYTREE_FILE

Absolute path to the CherryTree .ctd file

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

Available Tools

13 tools
add_bookmarkA

Add a node to bookmarks.

Args: node_id: Node ID.

Returns: Confirmation message followed by byte-by-byte audit report. On XML parse failure, backup is restored automatically (ROLLBACK).

Inputs: node_id (required). Returns: result

append_codebox_to_nodeA

Append a codebox (or raw XML content) to an existing node.

Args: node_id: Node ID. code: Code content (ignored if content_xml is set). syntax: Syntax language. text_before: Text before codebox (ignored if content_xml is set). text_after: Text after codebox (ignored if content_xml is set). content_xml: Raw CherryTree XML to append. See create_node docs for format.

Returns: Confirmation message followed by byte-by-byte audit report. On XML parse failure, backup is restored automatically (ROLLBACK).

Inputs: node_id (required), code, syntax, text_after, +2 more. Returns: result

create_nodeA

Create a new rich-text node.

Args: name: Node title. content: Plain text body (ignored if content_xml is set). content_xml: Raw CherryTree XML body — supports full formatting: <rich_text> segments with attributes (weight="heavy", foreground="#RRRRGGGGBBBB", background, style="italic", underline="single", strikethrough="true", scale="h1"|"h2"|"h3"|"h4"|"h5"|"h6"|"small"|"sup"|"sub", family="monospace", justification="left"|"center"|"right"|"fill", link="webs URL"|"node UID"|"file BASE64"|"fold BASE64", indent="1"-"3"), (char_offset, syntax_highlighting, frame_width, frame_height), (char_offset, col_widths), <encoded_png> (char_offset, anchor for anchors, filename for embedded files). char_offset = position in concatenated plain text where widget is rendered; each widget occupies 1 char in the count. parent_id: Parent node ID (0 = top-level). tags: Space-separated tags. is_bold: Bold title. foreground: Title color hex (48-bit GTK: #RRRRGGGGBBBB). custom_icon_id: Icon ID.

Returns: Confirmation message followed by byte-by-byte audit report: [AUDIT] readback, delta, change region, prefix/suffix integrity, node count, target node identification, XML parse result. On XML parse failure, backup is restored automatically (ROLLBACK).

Inputs: name (required), tags, content, is_bold, +4 more. Returns: result

create_node_with_codeboxA

Create a node with an embedded codebox.

If content_xml is provided, it is used as the full body (text_before/code/text_after ignored).

Args: name: Node title. text_before: Text before the codebox. code: Code content. syntax: Language (sh, python3, sql, java, etc.). text_after: Text after the codebox. parent_id: Parent node ID (0 = top-level). tags: Tags. content_xml: Raw CherryTree XML body (overrides other content params). See create_node docs.

Returns: Confirmation message followed by byte-by-byte audit report. On XML parse failure, backup is restored automatically (ROLLBACK).

Inputs: name (required), code, tags, syntax, +4 more. Returns: result

delete_nodeA

Delete a node and all its children.

Args: node_id: Node ID.

Returns: Confirmation message followed by byte-by-byte audit report. On XML parse failure, backup is restored automatically (ROLLBACK).

Inputs: node_id (required). Returns: result

list_bookmarksA

List all bookmarked nodes.

Inputs: no named parameters. Returns: result

list_nodesB

List nodes in the CherryTree tree.

Args: parent_id: Parent node ID (0 = top-level). depth: Levels to descend. include_path: Include breadcrumb paths.

Inputs: depth, parent_id, include_path. Returns: result

move_nodeA

Move a node under a different parent.

Args: node_id: Node to move. new_parent_id: Destination parent (0 = top-level).

Returns: Confirmation message followed by byte-by-byte audit report. On XML parse failure, backup is restored automatically (ROLLBACK).

Inputs: node_id (required), new_parent_id. Returns: result

read_nodeA

Read content of a CherryTree node.

Args: node_id: Node unique ID (preferred). node_name: Search by name (partial, case-insensitive). include_formatting: Return rich-text segment details. include_widgets: Return codebox/image/table/anchor details.

Inputs: node_id, node_name, include_widgets, include_formatting. Returns: result

remove_bookmarkA

Remove a node from bookmarks.

Args: node_id: Node ID.

Returns: Confirmation message followed by byte-by-byte audit report. On XML parse failure, backup is restored automatically (ROLLBACK).

Inputs: node_id (required). Returns: result

search_nodesA

Full-text search across all nodes.

Args: query: Search term (case-insensitive). max_results: Max results.

Inputs: query (required), max_results. Returns: result

update_node_contentA

Update content of a node.

WARNING: With append=False this REPLACES all body content (text, codeboxes, images, tables). Use append=True to safely add content at the end.

Returns: Confirmation message followed by byte-by-byte audit report. On XML parse failure, backup is restored automatically (ROLLBACK).

Args: node_id: Node ID. content: Plain text to set or append (ignored if content_xml is set). content_xml: Raw CherryTree XML body — supports full formatting. Accepts any combination of: <rich_text> segments with formatting attributes (weight="heavy" for bold, foreground="#RRRRGGGGBBBB", background, style="italic", underline="single", strikethrough="true", scale="h1"-"h6"|"small"|"sup"|"sub", family="monospace", justification, link="webs URL"|"node UID"|"file BASE64"|"fold BASE64", indent), (char_offset, syntax_highlighting, frame_width, frame_height), (char_offset, col_widths, with rows/cells), <encoded_png> (char_offset, anchor, filename, link). char_offset = position in concatenated plain text of all <rich_text> where the widget renders; each widget occupies exactly 1 char. append: True = append, False = replace.

Inputs: node_id (required), append, content, content_xml. Returns: result

update_node_propertiesA

Update node properties (name, tags, icon, etc.).

Args: node_id: Node ID. name: New title. tags: New tags. is_bold: Bold title. foreground: Title color hex. custom_icon_id: Icon ID. readonly: Read-only flag.

Returns: Confirmation message followed by byte-by-byte audit report. On XML parse failure, backup is restored automatically (ROLLBACK).

Inputs: node_id (required), name, tags, is_bold, +3 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools target distinct actions (list, read, search, create, update, delete, move, bookmark), so an agent can generally select correctly. The only mild overlap is create_node and create_node_with_codebox, since create_node can also embed codeboxes via content_xml, but the dedicated helper is clearly specialized.

    Naming Consistency5/5

    Tool names uniformly follow a verb_noun pattern: list_nodes, read_node, create_node, update_node_content, delete_node, move_node, add_bookmark, remove_bookmark. Even the longer names like append_codebox_to_node and create_node_with_codebox still follow the same predictable convention.

    Tool Count5/5

    13 tools is a well-scoped set for a CherryTree note-management server, covering reading, searching, writing, structure manipulation, and bookmarks without redundancy or bloat. Each tool earns its place and the count feels balanced for the domain.

    Completeness5/5

    The tool surface covers the full lifecycle of CherryTree nodes: list, read, search, create (regular and codebox), update content, update properties, append codebox, move, delete, plus complete bookmark management. There are no obvious dead ends for common note-editing workflows.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Full-featured Notion MCP server enabling deep page reading, block editing, snapshot/restore, file uploads, table manipulation, page restore, and destructive page copying.
      33
      108 PyPI
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that provides read and write access to an Obsidian vault by interacting directly with markdown files on disk. Supports searching, listing, reading, creating, editing, and appending notes without requiring any Obsidian plugins.
      ISC