Back to search
markmap-mcp-server
MCP serverGitHub
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
Markdown
[](/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)
- # Markmap MCP Server
- 
- [](https://www.npmjs.com/package/@jinzcdev/markmap-mcp-server)
- [](https://www.npmjs.com/package/@jinzcdev/markmap-mcp-server)
- [](LICENSE)
- [](README_zh-CN.md)
- [](https://github.com/jinzcdev/markmap-mcp-server)
- 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.
- ## 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
- ```bash
- npm install playwright
- npx playwright install chromium
- ```
- (`playwright` is an optional dependency of this package.)
- ## Installation
- ```bash
- # 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
- ```bash
- 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:
- ```bash
- 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
- ```
- ## Usage
- Add the following configuration to your MCP client (Cursor / Claude Desktop / etc.):
- ```json
- {
- "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"
- }
- }
- }
- }
- ```
- ### 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. |
- | `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`):**
- ```json
- {
- "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|svg` is what Agents can consume directly without a manual browser click.
- ### `list_mindmaps`
- 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}]}`.
- ### `get_mindmap`
- 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.
- ### `cleanup_mindmaps`
- 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 |
- ### Prompt: `mindmap_from_content`
- 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 |
- ## Related Projects
- | Project | Description |
- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
- | **[MarkXMind Online](https://github.com/jinzcdev/markxmind)** | Create XMind mind maps with Markdown online. [Try it →](https://markxmind.js.org/) |
- | **[Obsidian MarkXMind Plugin](https://github.com/jinzcdev/obsidian-markxmind)** | Render XMindMark syntax as XMind mind maps inside Obsidian. |
- ## License
- This project is licensed under the [MIT](./LICENSE) License.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.