CherryTree MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@CherryTree MCP Server search nodes for 'project plan' and show the tree"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 nodeslist_bookmarks— list nodes marked as favorites
Writing
create_node— create node (plain text or rich XML viacontent_xml)create_node_with_codebox— create node with codebox (or rich XML viacontent_xml)update_node_content— replace or append (plain text or rich XML viacontent_xml)append_codebox_to_node— add codebox or rich XML to an existing nodeupdate_node_properties— change name, tags, icon, color, readonlydelete_node— delete node and childrenmove_node— move node to another parent
Bookmarks
add_bookmark— add node to favoritesremove_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 |
|
| bold |
|
|
|
|
| highlight |
|
| italic |
|
| underlined |
|
| strikethrough |
|
| headings |
|
| monospaced |
|
| alignment |
|
| links |
|
| 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
lxmlfor XML parsing/queries (safe, no write-back)Writes use raw string manipulation to avoid
\rnormalization that corruptschar_offsetin unedited nodes (lxml/ETserialization bug)Backup
.ctd.bakcreated automatically before each writeAudit 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: OKIf 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.py3. Restart Claude Code
The tools appear automatically as mcp__cherrytree__<tool_name>.
Environment variables
Variable | Description |
| Absolute path to the CherryTree |
Requirements
Python >= 3.11
CherryTree v1.x (
.ctdXML format, not.ctbSQLite)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=Falseinupdate_node_contentreplace the entire node content (text, codeboxes, images, tables).
Available Tools
13 toolsadd_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
Scored across 13 tools
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.
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.
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.
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
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Turn outlines and hierarchical notes into interactive mind maps through a hosted remote MCP server.
Related MCP Servers
- AlicenseAqualityBmaintenanceFull-featured Notion MCP server enabling deep page reading, block editing, snapshot/restore, file uploads, table manipulation, page restore, and destructive page copying.33108 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceMCP 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
- AlicenseNot gradedqualityDmaintenanceMCP server for mind-wiki — access your personal knowledge wiki from any directory or MCP-compatible client.MIT
- AlicenseBqualityDmaintenancePython MCP server for programmatic access to markdown-based knowledge vaults, enabling AI assistants to browse, read, search, update, and manage notes, tasks, and projects.481MIT