Ygdria MCP Server
A local MCP server that connects MCP clients to the Ygdria desktop app's ETAPI so an agent can search, read, create, and edit notes and reorganize the placement tree — gated by a single "allow local tool access" toggle in the desktop app.
Search & discover: keyword search (
search_notes) with optional exact tag and placement subtree filters, exact-tag lookup (search_by_tag), and full tag listing (list_tags).Browse the tree: paginated roots and direct children, single-node metadata, bounded subtrees, name-fragment resolution (
resolve_tree_nodes), and an auto-paginatingget_tree_overviewwith node/depth/byte/request budgets plus continuation tokens.Read notes: single (
get_note, markdown/json/html) or batch up to 50 (get_notes) in metadata, excerpt, or full view with a byte budget that defers remaining IDs; read a unique heading section with its current version (get_section); notes exposed asygdria://note/{noteId}resources.Create notes: title plus optional content, tags, type, and parent placement, with optional idempotency keys safe for 30-day retries.
Edit notes: full-body replace, metadata/title/tag updates, atomic literal oldText/newText edits with a dry-run preview, and appends with a mandatory idempotency key — all protected by optimistic version checks.
Section surgery: replace the body under a unique heading path while preserving its heading and all outside nodes (
replace_section), using the exact text returned byget_section.Tags: add and remove up to 20 tags each while leaving unrelated tags intact.
Organize placements: move a single placement or up to 50 sequentially with per-item results and partial success.
Safety model: execution is gated by the desktop toggle (tools stay registered), loopback-only HTTP(S) origin enforced, no tokens or write flags, redirects refused, writes require versions/idempotency keys, and errors return parseable JSON with actionable next steps.
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., "@Ygdria MCP Server search my notes for project ideas"
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.
Ygdria MCP Server
本机 MCP ↔ Ygdria ETAPI 适配器。无需令牌,也无需单独开启 MCP 写权限;访问由 Ygdria 桌面应用中的一个开关控制。
使用
在 Ygdria 桌面设置中开启 AI 与外部访问 → 允许本机工具访问。
安装并构建本项目:
npm install
npm run build在 MCP 客户端配置本地 stdio 服务,例如:
{
"mcpServers": {
"ygdria": {
"command": "node",
"args": ["D:\\projects\\Ygdria-MCP\\dist\\index.js"]
}
}
}默认连接 http://127.0.0.1:4318。直接 npm start 可启动 stdio 服务;stdout 只用于 MCP 消息。需要 Node.js 18 或更高版本和正在运行的 Ygdria Desktop。
关闭桌面开关会立即阻止后续调用;重新开启后直接继续调用,无需重启 MCP。首次从旧版本升级仍需重启主服务和 MCP 以加载新实现。
Related MCP server: trilium-mcp
可选配置
通常不需要配置文件。自定义本机端口时,可填写 ygdria-mcp.ini:
[etapi]
url = http://127.0.0.1:4318也可用 YGDRIA_ETAPI_URL 覆盖地址,YGDRIA_CONFIG_FILE 指定配置文件。地址必须是 HTTP(S) loopback origin,不能包含路径、凭据或远程主机。修改地址需重启。
旧 token、allowWrite 以及对应环境变量不再使用,可从配置中删除;不会发送旧令牌。MCP 自动添加 X-Ygdria-External-Access: 1,拒绝跟随 HTTP 重定向。Ygdria 另外校验 socket、Host 和浏览器请求头;桌面私有 API 仍受独立凭据保护。
工具
工具 | 用途 |
| 关键词、标签、目录组合搜索与标签统计。 |
| 分页浏览 placement。 |
| 有界子树和按名称定位。 |
| 自动分页展开;限制节点、深度、条目字节数和请求数,返回截断状态及续读位置。 |
| 单篇或最多 50 篇批量读取;批量支持 metadata、excerpt、full。 |
| 按标题祖先路径读取唯一章节的正文和版本。 |
| 在任务授权范围内创建,支持幂等键。 |
| 上传 Base64 图片,返回附件 URL 和 Markdown;再通过带版本的正文编辑插入。相同图片按内容哈希去重。 |
| 带版本更新元数据或正文。 |
| oldText/newText 字面精确编辑;支持预览。 |
| 追加 Markdown 块或字面代码;必须带幂等键。 |
| 增删指定标签并保留其他标签,超限报错。 |
| 用 get_section 返回的正文和版本替换章节,保留标题和章节外节点。 |
| 单个或最多 50 个顺序批量移动,逐项报告结果。 |
所有工具始终注册,执行权限由桌面开关决定。用户已授权的任务可连续完成必要操作,无需每步重复确认;MCP 客户端自身的确认策略仍由客户端决定。受保护笔记、系统节点保护和正文乐观并发继续有效。
笔记 Resource 为 ygdria://note/{noteId},返回 Markdown 和版本标记。树节点使用 placementId,笔记使用 noteId。
图片导入要求主服务支持 POST /etapi/notes/:id/images(旧版返回 404,需升级并重启主服务)。先创建或读取目标笔记,调用 upload_image 传入文件名和标准 Base64 图片字节(不含 data: 前缀),再将返回的 markdown 通过带当前版本的正文编辑插入。支持 PNG、JPEG、GIF、WebP、SVG,单图最大 20 MiB。上传不修改正文;相同图片按内容哈希去重,未引用的图片遵循主服务附件清理规则。不要把 Base64 图片链接直接写入正文。
目录概览的字节预算约束 items,续读元数据另计。continuation 原样传入下一次调用,并保持 maxDepth/includeArchived 一致;遍历不是快照,结构变化时可能需要重新开始。指定 placement 时返回其后代。深度未展开节点单独列出。
批量读取超过预算返回 remainingNoteIds,单篇过大时改用 excerpt 或 get_note。批量移动允许部分成功,不构成跨请求事务;遇到访问被关闭时停止。
创建建议使用 idempotencyKey,追加必须使用。同一本机数据库和操作目标下,30 天内使用相同键和相同参数可安全重试;不同参数复用键返回 409。带键写入返回 { id, version, updatedAt } 原始回执,正文另行读取。回执由主服务同事务持久保存,关闭/开启开关和重启不会改变其身份;恢复旧数据库备份或超过 30 天后不保证去重。未带键的创建不能盲目重试。
错误返回可解析 JSON,包含状态、业务详情及下一步操作;5xx 隐藏内部详情。403 时先检查桌面开关和本机连接条件。409 重新读取内容后判断,不覆盖新版本;422 修正精确编辑目标,不自动模糊替换。
验证
npm run typecheck
npm testAvailable Tools
21 toolsappend_contentAIdempotent
Append Markdown blocks (or literal code) to the latest note without replacing existing content. Required idempotencyKey makes retries safe for 30 days on the same local Ygdria database. Optionally require expectedVersion.
Inputs: text (required), noteId (required), idempotencyKey (required), expectedVersion.
create_noteCreate a Ygdria noteB
Create a note within the user-authorized task, including necessary notes for organizing or summarizing. Use a unique idempotencyKey; on an uncertain network result retry only with the same key and identical parameters within 30 days.
Inputs: title (required), tags, type, content, +2 more.
edit_contentPrecisely edit Ygdria note contentADestructive
Apply atomic literal oldText/newText edits to a note read earlier with get_note. Each target must match exactly as expected; use dryRun to preview.
Inputs: edits (required), noteId (required), dryRun, version, +1 more.
get_noteRead a Ygdria noteBRead-only
Read a note through ETAPI. Read current content before replacing existing text; retain the returned version. A current note resource or prior write response can also supply the version.
Inputs: noteId (required), format.
get_notesARead-only
Read up to 50 notes with per-note results. Choose metadata, excerpt, or full Markdown; a byte budget defers remaining IDs for another call. Protected notes remain inaccessible.
Inputs: noteIds (required), view, maxBytes, excerptLength.
get_sectionARead-only
Read a unique heading section body and current version. Pass the returned content unchanged as oldText to replace_section; headingPath lists ancestor titles and the target heading.
Inputs: noteId (required), headingPath (required).
get_tree_nodeGet a Ygdria tree nodeCRead-only
Read compact metadata for exactly one placement node.
Inputs: placementId (required), includeArchived.
get_tree_overviewARead-only
Explore roots or a placement's descendants automatically within node, depth, item-byte, and request budgets. Pass returned continuation to continue; depth-limited nodes are listed separately. Byte budget covers items; continuation is additional bounded navigation data.
Inputs: maxBytes, maxDepth, maxNodes, maxRequests, +3 more.
get_tree_subtreeGet a bounded Ygdria subtreeARead-only
Read one placement and its descendants within explicit depth and node limits; use get_tree_overview to explore across roots within a response budget.
Inputs: placementId (required), maxDepth, maxNodes, includeArchived.
list_tagsList Ygdria tagsBRead-only
List all tags available through Ygdria ETAPI.
Inputs: no named parameters.
list_tree_childrenList direct Ygdria tree childrenBRead-only
List direct child placement nodes, paginated. Use hasChildren to decide whether further expansion is useful.
Inputs: placementId (required), limit, cursor, includeArchived.
list_tree_rootsList Ygdria tree rootsARead-only
List only top-level tree nodes, paginated. Use resolve_tree_nodes for direct lookup or get_tree_overview for a budgeted overview.
Inputs: limit, cursor, includeArchived.
move_placementMove a Ygdria placementCIdempotent
Move a placement tree node. placementId, not noteId, identifies the item being moved.
Inputs: position (required), placementId (required), parentPlacementId (required).
move_placementsA
Move up to 50 placements sequentially. Each move is independent; returns per-item results and partial success, without cross-request atomicity. Stops on authentication or permission errors.
Inputs: moves (required).
replace_contentReplace Ygdria note contentADestructive
Replace the complete Markdown body using the version from a prior get_note call as If-Match.
Inputs: noteId (required), content (required), version, expectedVersion.
replace_sectionADestructive
Replace the body under a unique hierarchy of heading titles, preserving its heading and all outside Tiptap nodes. Use get_section first. oldText is the exact returned Markdown section body, including nested subsections. Requires current expectedVersion. Ambiguous paths fail atomically.
Inputs: text (required), noteId (required), oldText (required), headingPath (required), +2 more.
resolve_tree_nodesResolve Ygdria tree nodes by nameBRead-only
Find candidate placement nodes by a title fragment, then navigate with their placementId values.
Inputs: query (required), limit, includeArchived, parentPlacementId.
search_by_tagSearch Ygdria notes by tagARead-only
Find notes with an exact Ygdria tag, optionally limited to a placement and all its descendants.
Inputs: tag (required), placementId, includeArchived.
search_notesSearch Ygdria notesBRead-only
Search Ygdria notes through ETAPI. Optionally limit results to a placement and all its descendants. Results use noteId for follow-up note tools; snippets are plain text.
Inputs: query (required), tag, placementId, includeArchived.
update_noteUpdate a Ygdria noteA
Update title, body, or tags using the current version from a read, resource, or prior write response. On conflict, this tool reads and returns the latest note; reconsider the edit and never retry the stale version.
Inputs: noteId (required), expectedVersion (required), tags, title, +2 more.
update_tagsB
Add and remove tags on the latest note without replacing unrelated tags. Additions win if a tag appears in both lists.
Inputs: noteId (required), addTags, removeTags, idempotencyKey, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
The set has several overlapping clusters: tree exploration is split across list_tree_roots, get_tree_node, list_tree_children, get_tree_subtree, resolve_tree_nodes, and get_tree_overview, and content modification is split across update_note, edit_content, replace_content, append_content, and replace_section. Descriptions do provide guidance on when to use each, but an agent can still hesitate between the budgeted overview tools and the explicit subtree tools.
Tool names consistently use snake_case and a predictable verb_noun or verb_prep_noun pattern, such as search_notes, get_note, create_note, update_tags, replace_section, and move_placement. Singular/plural distinctions like move_placement versus move_placements are also clear and intentional.
With 21 tools, the server is on the heavy side for a note/tree API and has many specialized navigation and editing operations. The count is not extreme, but it is borderline enough that agents must choose among several similarly scoped tree and content tools.
The surface covers note search, reading, creation, updates, content editing, tag updates, and placement moves well. However, there are notable lifecycle gaps: no delete_note or delete_placement tools and no explicit tool for creating or deleting placement tree nodes, which may cause dead ends for full resource management.
Related MCP Connectors
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Official MCP bridge to Exogram—the Personal AI Agent for your work, people, and life.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for AI agents to read, write, and organize notes in a local-first, human-in-the-loop note-taking app.2MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that lets AI agents read and write a self-hosted TriliumNext knowledge base over its ETAPI, enabling note capture, structured table maintenance, and search.5MIT
- FlicenseNot gradedqualityAmaintenanceEnables users to create, link, explore, and synthesize atomic notes as a knowledge graph through Claude and other MCP-compatible clients. It supports tagging, search, note types, semantic link types, and Markdown-file storage indexed by SQLite.-
- FlicenseNot gradedqualityAmaintenanceEnables creating, linking, searching, exploring, and synthesizing atomic notes as a knowledge graph through MCP-compatible clients such as Claude. Supports tags, note types, semantic relationships, Markdown storage, and an SQLite index for efficient traversal.-