jinzcdev/markmap-mcp-server

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.
Features
- **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 --offline inlines 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
Prerequisites
1. Node.js **v20 or above**
2. For **server-side image export** (format: png|jpg|svg): install Playwright and Chromium
(playwright is an optional dependency of this package.)
Installation
Docker
Or clone and run locally:
Usage
Add the following configuration to your MCP client (Cursor / Claude Desktop / etc.):
Server preferences (CLI / env)
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.
Example prompts
- “Summarize this design doc as a mind map.”
- “Convert ./notes/architecture.md to a mind map.”
- “Generate a PNG mind map of this outline for the chat.”
Available Tools
markdown_to_mindmap
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. |