Markmap MCP Server

What jinzcdev/markmap-mcp-server MCP server does

The jinzcdev/markmap-mcp-server MCP server turns Markdown structure into visual mind maps using markmap. Headings and nested list items become the hierarchy in an interactive HTML document. The generated viewer includes zoom and collapse behavior, a browser export toolbar, and a Markdown copy action.

The main generation tool accepts Markdown directly or an absolute path to a local .md file. It can produce HTML by default, or create PNG, JPG, or SVG output in addition to the HTML source. Generated files are written beneath the configured output directory. If a filename is reused, the existing generated file is overwritten.

The server also supports a local file workflow. list_mindmaps finds recent files whose names begin with markmap, get_mindmap retrieves a generated file, and cleanup_mindmaps removes generated files according to age or an all-files option.

How it works

The jinzcdev/markmap-mcp-server MCP server runs locally over MCP and does not call external APIs or require third-party service credentials. HTML generation is normally quick. Image export starts a headless Chromium process through Playwright and requires both the Playwright package and its Chromium browser installation.

Generation always creates an HTML source file. For an image request, the image becomes the primary artifact while the HTML path remains available in the response. Return behavior is controlled at startup: path returns file paths, content returns inline HTML or an MCP image block where supported, and both returns paths plus inline content. Large HTML output can fall back to paths.

Browser opening is also a startup preference. The server can always open a browser, never open one, or expose an agent-controlled option. The default is never. Offline mode can inline page assets so generated HTML does not depend on CDN access.

Setup and configuration

Node.js 20 or newer is required. The package can be run directly with npx:

npx -y @jinzcdev/markmap-mcp-server

Set the output location with --output or MARKMAP_DIR; the default is ~/.markmap-mcp. MARKMAP_OPEN or --open controls browser behavior, and MARKMAP_RETURN_MODE or --return-mode controls response content. Use --offline or MARKMAP_OFFLINE=true to enable self-contained HTML. Command-line flags take precedence over environment variables.

For PNG, JPG, or SVG export, install Playwright and Chromium separately:

npm install playwright
npx playwright install chromium

The README shows stdio configurations for Claude Desktop and Cursor. A Docker workflow is also documented, using /data/markmap as the container output location through MARKMAP_DIR.

Tools and capabilities

• markdown_to_mindmap accepts Markdown or a local Markdown path and supports html, png, jpg, and svg formats.
• list_mindmaps lists matching generated files newest first and has a configurable limit.
• get_mindmap reads a file only when its absolute path remains inside the configured output directory. Small HTML and SVG files can include text content; PNG and JPG results provide metadata only.
• cleanup_mindmaps deletes files older than a selected number of days or all matching files. Use dryRun=true first to preview deletion because the default is destructive.
• The mindmap_from_content prompt helps structure notes as Markdown before calling the generation tool.

Limitations and notes

The input should already express a hierarchy through headings or nested lists. Flat, unstructured text is not the intended input. The server writes local files and does not provide cloud storage or external mind-map APIs.

Image export is slower than HTML and depends on a working Playwright Chromium installation. get_mindmap rejects paths outside the configured output directory. PNG and JPG retrieval returns metadata rather than image content, so regenerate with an image format when the agent needs pixels. Cleanup is irreversible when dryRun is false, so preview targets before committing deletion.