Markmap MCP Server is based on the Model Context Protocol (MCP). It converts Markdown into interactive mind maps using markmap, and can optionally export PNG / JPG / SVG on the server for Agent-friendly delivery. Generation runs locally — no third-party API keys required.
- Markdown → Mind Map: Convert Markdown (headings + nested lists) to interactive HTML mind maps
- Agent-friendly returns: Return a file path, inline HTML, and/or image content (configured at startup)
- Server-side export: Export PNG / JPG / SVG via Playwright for chat/inline preview
- Browser preview: Configurable open behavior — always, never, or agent-decided (startup setting)
- Browser export toolbar: When viewing HTML, also export PNG/JPG/SVG or copy Markdown in the page UI
- Offline HTML: Startup
--offlineinlines assets so the page works without CDN access - File workflows: Read from
inputPath, list recent outputs, clean up old files - Privacy-first: Fully local conversion; no cloud mind-map API
- Node.js v20 or above
- For server-side image export (
format: png|jpg|svg): install Playwright and Chromium
npm install playwright
npx playwright install chromium(playwright is an optional dependency of this package.)
# Install from npm
npm install @jinzcdev/markmap-mcp-server -g
# Basic run
npx -y @jinzcdev/markmap-mcp-server
# Specify output directory and auto-open in browser
npx -y @jinzcdev/markmap-mcp-server --output /path/to/output/directory --open alwaysdocker build -t markmap-mcp-server .
docker run --rm -i \
-v /path/to/output:/data/markmap \
-e MARKMAP_DIR=/data/markmap \
markmap-mcp-serverOr clone and run locally:
git clone https://github.com/jinzcdev/markmap-mcp-server.git
cd markmap-mcp-server
npm install && npm run build
# Optional: enable server-side image export
npx playwright install chromium
node build/index.jsAdd the following configuration to your MCP client (Cursor / Claude Desktop / etc.):
{
"mcpServers": {
"markmap": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@jinzcdev/markmap-mcp-server"],
"env": {
"MARKMAP_DIR": "/path/to/output/directory",
"MARKMAP_OPEN": "never",
"MARKMAP_RETURN_MODE": "path"
}
}
}
}These are decided when the server starts — not tool arguments:
| Preference | CLI | Env | Values | Default |
|---|---|---|---|---|
| Output directory | --output / -o |
MARKMAP_DIR |
any directory path | ~/.markmap-mcp |
| Open in browser | --open [mode] |
MARKMAP_OPEN |
always | never | agent (bare --open = always) |
never |
| Return mode | --return-mode |
MARKMAP_RETURN_MODE |
path | content | both |
path |
| Offline HTML | --offline |
MARKMAP_OFFLINE |
true | false (CLI: pass --offline to enable) |
false |
CLI flags override environment variables. --output overrides MARKMAP_DIR.
--open: bare --open means always. You may also pass --open always|never|agent. An invalid value exits with an error. Without the flag, MARKMAP_OPEN is used (default never).
Return mode:
| Mode | Meaning |
|---|---|
path |
Paths JSON only (htmlFilePath + filePath) |
content |
Inline content only (raw HTML text, or a base64 image block) — no paths |
both |
Paths JSON plus inline content |
Generated HTML always includes the markmap toolbar, English export labels, and fully expanded nodes.
- “Summarize this design doc as a mind map.”
- “Convert
./notes/architecture.mdto a mind map.” - “Generate a PNG mind map of this outline for the chat.”
Convert Markdown into an interactive mind map (and optionally an image).
| Parameter | Type | Default | Description |
|---|---|---|---|
markdown |
string | — | Markdown content (required unless inputPath is set). Wins when both are provided. |
inputPath |
string | — | Absolute path to a local .md file |
format |
html | png | svg | jpg |
html |
Output format. Image formats need Playwright |
filename |
string | auto | Output base name (sanitized; prefixed with markmap- if needed; reusing overwrites) |
open |
boolean | false |
Whether to open the result in browser. Only exposed when server open mode is agent (--open agent / MARKMAP_OPEN=agent). |
Return (returnMode=path):
{
"htmlFilePath": "/path/to/markmap-….html",
"filePath": "/path/to/markmap-….html"
}For image formats, filePath is the image path and htmlFilePath is still the HTML source.
Return (returnMode=content): Raw HTML text block, or an MCP image content block (base64) for png/jpg/svg — no paths JSON. Oversized HTML (≥200KB) falls back to paths JSON.
Return (returnMode=both): Paths JSON plus the inline content above.
Note: Interactive zoom/collapse and the in-page “Export PNG/JPG/SVG” buttons are part of the HTML viewer. Server-side
format: png|jpg|svgis what Agents can consume directly without a manual browser click.
List recent generated files in the output directory (newest first). Only files whose names start with markmap are included.
| Parameter | Type | Default | Description |
|---|---|---|---|
limit |
number | 20 |
Max files to return (1–200) |
Returns {outputDir, files: [{name, filePath, size, mtimeMs, mtime}]}.
Retrieve a generated mind map file by its absolute path. Path must stay inside the configured output directory (path traversal denied).
| Parameter | Type | Default | Description |
|---|---|---|---|
filePath |
string | — | Absolute path to the mind map file (HTML or image) |
Returns JSON {filePath, mimeType, size}. For HTML/SVG under 200KB, also appends a text content block. PNG/JPG return metadata only (no image block) — re-export via markdown_to_mindmap with format=png\|jpg if pixels are needed.
Delete old (or all) generated mind map files.
| Parameter | Type | Default | Description |
|---|---|---|---|
maxAgeDays |
number | 7 |
Delete files older than this many days |
all |
boolean | false |
If true, delete all markmap files |
dryRun |
boolean | false |
If true, preview without deleting |
Helper prompt that asks the model to structure notes as Markdown, then call markdown_to_mindmap.
| Parameter | Type | Default | Description |
|---|---|---|---|
topic |
string | — | Topic or raw notes to organize as a map |
| Project | Description |
|---|---|
| MarkXMind Online | Create XMind mind maps with Markdown online. Try it → |
| Obsidian MarkXMind Plugin | Render XMindMark syntax as XMind mind maps inside Obsidian. |
This project is licensed under the MIT License.