Edit markdown files structurally (parse tree, insert/move/delete blocks, search, undo) via markdown-editor-mcp-server (uvx)
Agent task: edit a markdown document by structural path rather than line numbers or regex. Parse the heading tree, address any block as "Section > Subsection > paragraph 2", then insert, replace, move, or delete elements while the server maintains document integrity. Includes undo, frontmatter editing, and text search.
Recipe: structurally edit markdown via markdown-editor-mcp-server (uvx)
Server: [email protected] · uvx-ready · stdio · no auth · pure local Tools (16): get_document_structure, read_element, search_text, get_context, replace_content, insert_element, move_element, delete_element, update_metadata (frontmatter), undo, search_tools, list_directory, create_file, create_directory, delete_item
How to run
echo '<jsonrpc lines>' | uvx markdown-editor-mcp-serverKey concept: path-based addressing
Every element in the document is addressable by a heading path like "Project Alpha > Features > list 1 > item 2". Call get_document_structure first to discover the tree, then use paths to read, edit, insert, move, or delete any block.
Workflow (4 operations, all verified)
1. Parse structure — get the heading tree with element types and paths:
{"method":"tools/call","params":{"name":"get_document_structure","arguments":{"file_path":"/tmp/test-recipe.md","depth":3}}}Returns a nested tree:
Project Alpha (h1)
├── Overview (h2) → paragraph 1
├── Features (h2) → list 1 → [item 1, item 2]
├── Installation (h2) → paragraph 1
└── License (h2) → paragraph 12. Read a specific element by path:
{"method":"tools/call","params":{"name":"read_element","arguments":{"file_path":"/tmp/test-recipe.md","path":"Project Alpha > Features > list 1"}}}→ {"type":"list","path":"Project Alpha > Features > list 1","children_count":2}
3. Insert a new block (paragraph after Features heading):
{"method":"tools/call","params":{"name":"insert_element","arguments":{"file_path":"/tmp/test-recipe.md","path":"Features","element_type":"paragraph","content":"These are the core capabilities of the project.","where":"after"}}}→ {"success":true,"new_path":"Project Alpha > paragraph 1"} — file modified on disk
4. Search text across the document:
{"method":"tools/call","params":{"name":"search_text","arguments":{"file_path":"/tmp/test-recipe.md","query":"npm"}}}→ {"results":[{"path":"Project Alpha > Installation > paragraph 1","type":"paragraph","preview":"Run \npm install\ to get started."}],"count":1}
Other capabilities (not exercised this run)
replace_content— overwrite any block's contentmove_element— reorder sections or blocksdelete_element— remove blocksupdate_metadata— set/modify YAML frontmatterundo— revert the last N operationsget_context— get an element plus its neighbors
Agent integration pattern
Use get_document_structure first to discover addressable paths. Then use path-based operations instead of line-number edits or regex. The undo capability makes it safe for exploratory edits. Ideal for changelog management, README updates, or any structured document maintenance.
{ "server": "markdown-editor-mcp-server", "version": "1.27.2", "transport": "stdio", "launcher": "uvx markdown-editor-mcp-server", "tools_count": 16, "tools_exercised": ["get_document_structure", "read_element", "insert_element", "search_text"], "trace": [ { "tool": "get_document_structure", "request": { "file_path": "/tmp/test-recipe.md", "depth": 3 }, "response": { "structure": [ { "type": "heading", "path": "Project Alpha", "level": 1, "children": [ { "type": "heading", "path": "Project Alpha > Overview", "level": 2, "children": [ { "type": "paragraph", "path": "Project Alpha > Overview > paragraph 1", "preview": "A sample project for testing." } ] }, { "type": "heading", "path": "Project Alpha > Features", "level": 2, "children": [ { "type": "list", "path": "Project Alpha > Features > list 1", "children": [ { "type": "list_item", "path": "Project Alpha > Features > list 1 > item 1", "preview": "Feature one" }, { "type": "list_item", "path": "Project Alpha > Features > list 1 > item 2", "preview": "Feature two" } ] } ] }, { "type": "heading", "path": "Project Alpha > Installation", "level": 2 }, { "type": "heading", "path": "Project Alpha > License", "level": 2 } ] } ] } }, { "tool": "read_element", "request": { "file_path": "/tmp/test-recipe.md", "path": "Project Alpha > Features > list 1" }, "response": { "type": "list", "path": "Project Alpha > Features > list 1", "children_count": 2 } }, { "tool": "insert_element", "request": { "file_path": "/tmp/test-recipe.md", "path": "Features", "element_type": "paragraph", "content": "These are the core capabilities of the project.", "where": "after" }, "response": { "success": true, "new_path": "Project Alpha > paragraph 1" } }, { "tool": "search_text", "request": { "file_path": "/tmp/test-recipe.md", "query": "npm" }, "response": { "results": [ { "path": "Project Alpha > Installation > paragraph 1", "type": "paragraph", "preview": "Run `npm install` to get started." } ], "count": 1 } } ], "executed_at": "2026-06-12T17:19:00Z" }