Skip to content
Back to search

markmap-mcp-server

An MCP server for converting Markdown to interactive mind maps with export support (PNG/JPG/SVG).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jinzcdev--markmap-mcp-server/badge.svg)](/listings/jinzcdev--markmap-mcp-server)

HTML

<a href="/listings/jinzcdev--markmap-mcp-server"><img src="/api/listings/jinzcdev--markmap-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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 always

Docker

docker build -t markmap-mcp-server .
docker run --rm -i \
  -v /path/to/output:/data/markmap \
  -e MARKMAP_DIR=/data/markmap \
  markmap-mcp-server

Or 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.js

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 200 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Markmap MCP Server
  2. ![Sample Mindmap](./docs/markmap.svg)
  3. [![NPM Version](https://img.shields.io/npm/v/@jinzcdev/markmap-mcp-server.svg)](https://www.npmjs.com/package/@jinzcdev/markmap-mcp-server)
  4. [![NPM Downloads](https://img.shields.io/npm/dm/@jinzcdev/markmap-mcp-server.svg)](https://www.npmjs.com/package/@jinzcdev/markmap-mcp-server)
  5. [![GitHub License](https://img.shields.io/github/license/jinzcdev/markmap-mcp-server.svg)](LICENSE)
  6. [![中文文档](https://img.shields.io/badge/简体中文-查看-blue)](README_zh-CN.md)
  7. [![Stars](https://img.shields.io/github/stars/jinzcdev/markmap-mcp-server)](https://github.com/jinzcdev/markmap-mcp-server)
  8. Markmap MCP Server is based on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction). It converts Markdown into interactive mind maps using [markmap](https://github.com/markmap/markmap), and can optionally export **PNG / JPG / SVG on the server** for Agent-friendly delivery. Generation runs **locally** — no third-party API keys required.
  9. ## Features
  10. - **Markdown → Mind Map**: Convert Markdown (headings + nested lists) to interactive HTML mind maps
  11. - **Agent-friendly returns**: Return a file path, inline HTML, and/or image content (configured at startup)
  12. - **Server-side export**: Export PNG / JPG / SVG via Playwright for chat/inline preview
  13. - **Browser preview**: Configurable open behavior — always, never, or agent-decided (startup setting)
  14. - **Browser export toolbar**: When viewing HTML, also export PNG/JPG/SVG or copy Markdown in the page UI
  15. - **Offline HTML**: Startup `--offline` inlines assets so the page works without CDN access
  16. - **File workflows**: Read from `inputPath`, list recent outputs, clean up old files
  17. - **Privacy-first**: Fully local conversion; no cloud mind-map API
  18. ## Prerequisites
  19. 1. Node.js **v20 or above**
  20. 2. For **server-side image export** (`format: png|jpg|svg`): install Playwright and Chromium
  21. ```bash
  22. npm install playwright
  23. npx playwright install chromium
  24. ```
  25. (`playwright` is an optional dependency of this package.)
  26. ## Installation
  27. ```bash
  28. # Install from npm
  29. npm install @jinzcdev/markmap-mcp-server -g
  30. # Basic run
  31. npx -y @jinzcdev/markmap-mcp-server
  32. # Specify output directory and auto-open in browser
  33. npx -y @jinzcdev/markmap-mcp-server --output /path/to/output/directory --open always
  34. ```
  35. ### Docker
  36. ```bash
  37. docker build -t markmap-mcp-server .
  38. docker run --rm -i \
  39. -v /path/to/output:/data/markmap \
  40. -e MARKMAP_DIR=/data/markmap \
  41. markmap-mcp-server
  42. ```
  43. Or clone and run locally:
  44. ```bash
  45. git clone https://github.com/jinzcdev/markmap-mcp-server.git
  46. cd markmap-mcp-server
  47. npm install && npm run build
  48. # Optional: enable server-side image export
  49. npx playwright install chromium
  50. node build/index.js
  51. ```
  52. ## Usage
  53. Add the following configuration to your MCP client (Cursor / Claude Desktop / etc.):
  54. ```json
  55. {
  56. "mcpServers": {
  57. "markmap": {
  58. "type": "stdio",
  59. "command": "npx",
  60. "args": ["-y", "@jinzcdev/markmap-mcp-server"],
  61. "env": {
  62. "MARKMAP_DIR": "/path/to/output/directory",
  63. "MARKMAP_OPEN": "never",
  64. "MARKMAP_RETURN_MODE": "path"
  65. }
  66. }
  67. }
  68. }
  69. ```
  70. ### Server preferences (CLI / env)
  71. These are decided when the server starts — **not** tool arguments:
  72. | Preference | CLI | Env | Values | Default |
  73. | ---------------- | ----------------- | --------------------- | --------------------------------------------------------- | ---------------- |
  74. | Output directory | `--output` / `-o` | `MARKMAP_DIR` | any directory path | `~/.markmap-mcp` |
  75. | Open in browser | `--open [mode]` | `MARKMAP_OPEN` | `always` \| `never` \| `agent` (bare `--open` = `always`) | `never` |
  76. | Return mode | `--return-mode` | `MARKMAP_RETURN_MODE` | `path` \| `content` \| `both` | `path` |
  77. | Offline HTML | `--offline` | `MARKMAP_OFFLINE` | `true` \| `false` (CLI: pass `--offline` to enable) | `false` |
  78. CLI flags override environment variables. `--output` overrides `MARKMAP_DIR`.
  79. **`--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`).
  80. **Return mode:**
  81. | Mode | Meaning |
  82. | --------- | ----------------------------------------------------------------------- |
  83. | `path` | Paths JSON only (`htmlFilePath` + `filePath`) |
  84. | `content` | Inline content only (raw HTML text, or a base64 image block) — no paths |
  85. | `both` | Paths JSON plus inline content |
  86. Generated HTML always includes the markmap toolbar, English export labels, and fully expanded nodes.
  87. ### Example prompts
  88. - “Summarize this design doc as a mind map.”
  89. - “Convert `./notes/architecture.md` to a mind map.”
  90. - “Generate a PNG mind map of this outline for the chat.”
  91. ## Available Tools
  92. ### `markdown_to_mindmap`
  93. Convert Markdown into an interactive mind map (and optionally an image).
  94. | Parameter | Type | Default | Description |
  95. | ----------- | --------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
  96. | `markdown` | string | — | Markdown content (required unless `inputPath` is set). Wins when both are provided. |
  97. | `inputPath` | string | — | Absolute path to a local `.md` file |
  98. | `format` | `html` \| `png` \| `svg` \| `jpg` | `html` | Output format. Image formats need Playwright |
  99. | `filename` | string | auto | Output base name (sanitized; prefixed with `markmap-` if needed; reusing overwrites) |
  100. | `open` | boolean | `false` | Whether to open the result in browser. **Only exposed when server open mode is `agent`** (`--open agent` / `MARKMAP_OPEN=agent`). |
  101. **Return (`returnMode=path`):**
  102. ```json
  103. {
  104. "htmlFilePath": "/path/to/markmap-….html",
  105. "filePath": "/path/to/markmap-….html"
  106. }
  107. ```
  108. For image formats, `filePath` is the image path and `htmlFilePath` is still the HTML source.
  109. **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.
  110. **Return (`returnMode=both`):** Paths JSON plus the inline content above.
  111. > **Note:** Interactive zoom/collapse and the in-page “Export PNG/JPG/SVG” buttons are part of the **HTML viewer**. Server-side `format: png|jpg|svg` is what Agents can consume directly without a manual browser click.
  112. ### `list_mindmaps`
  113. List recent generated files in the output directory (newest first). Only files whose names start with `markmap` are included.
  114. | Parameter | Type | Default | Description |
  115. | --------- | ------ | ------- | --------------------------- |
  116. | `limit` | number | `20` | Max files to return (1–200) |
  117. Returns `{outputDir, files: [{name, filePath, size, mtimeMs, mtime}]}`.
  118. ### `get_mindmap`
  119. Retrieve a generated mind map file by its absolute path. Path must stay inside the configured output directory (path traversal denied).
  120. | Parameter | Type | Default | Description |
  121. | ---------- | ------ | ------- | -------------------------------------------------- |
  122. | `filePath` | string | — | Absolute path to the mind map file (HTML or image) |
  123. 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.
  124. ### `cleanup_mindmaps`
  125. Delete old (or all) generated mind map files.
  126. | Parameter | Type | Default | Description |
  127. | ------------ | ------- | ------- | -------------------------------------- |
  128. | `maxAgeDays` | number | `7` | Delete files older than this many days |
  129. | `all` | boolean | `false` | If true, delete all markmap files |
  130. | `dryRun` | boolean | `false` | If true, preview without deleting |
  131. ### Prompt: `mindmap_from_content`
  132. Helper prompt that asks the model to structure notes as Markdown, then call `markdown_to_mindmap`.
  133. | Parameter | Type | Default | Description |
  134. | --------- | ------ | ------- | --------------------------------------- |
  135. | `topic` | string | — | Topic or raw notes to organize as a map |
  136. ## Related Projects
  137. | Project | Description |
  138. | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
  139. | **[MarkXMind Online](https://github.com/jinzcdev/markxmind)** | Create XMind mind maps with Markdown online. [Try it →](https://markxmind.js.org/) |
  140. | **[Obsidian MarkXMind Plugin](https://github.com/jinzcdev/obsidian-markxmind)** | Render XMindMark syntax as XMind mind maps inside Obsidian. |
  141. ## License
  142. This project is licensed under the [MIT](./LICENSE) License.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.