# jinzcdev/markmap-mcp-server [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/jinzcdev/markmap-mcp-server  
**GitHub Stars:** 284  
**npm Downloads (last month):** 3480  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/jinzcdev-markmap-mcp-server

## Description
An MCP server built on markmap that converts Markdown to interactive mind maps. Supports multi-format exports (PNG/JPG/SVG), live browser preview, one-click Markdown copy, and dynamic visualization features.

## Tools
Capabilities this server exposes over MCP:

- **markdown_to_mindmap** — Convert structured Markdown (headings # and nested lists -) into an interactive mind map HTML file, with optional server-side PNG/JPG/SVG export.

Use when the user wants a visual mind map/outline of structured content (architecture, plans, notes, hierarchies), or asks to visualize / mindmap / diagram. Do not use for flat unstructured text (restructure first), or to list/read existing outputs (use list_mindmaps / get_mindmap).

Behavior:
- WRITES files under the configured output dir. HTML is always written; image formats write an extra file. Reusing filename overwrites.
- html is fast (<1s). png/svg/jpg launch headless Chromium via Playwright (5–15s; requires: npm install playwright && npx playwright install chromium).
- Local only — no external APIs or third-party keys. Open mode=never: The server never opens the browser.
- Offline=false (server config).

Response:
- JSON {"htmlFilePath":"<path>","filePath":"<path>"} — htmlFilePath is always the HTML source; filePath is the primary artifact (HTML or image).
- Return mode=path: Paths JSON only — no inline content.
- Errors: isError:true with {"error","message"}.
- **list_mindmaps** — List markmap* files (html/png/jpg/jpeg/svg) in the output directory, newest first. Read-only — no side effects. Missing/empty dirs return {"files":[]}.

Returns: {"outputDir","files":[{"name","filePath","size","mtimeMs","mtime"}]} (mtime is ISO 8601).

Use before get_mindmap to discover paths, or before cleanup_mindmaps to preview targets. Not for generating new mind maps (use markdown_to_mindmap).
- **get_mindmap** — Retrieve a generated mind map file by absolute path. Read-only — no side effects. Only paths inside the configured output directory are allowed (path traversal denied).

Returns JSON {"filePath","mimeType","size"}. For text/html or image/svg+xml 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 the agent needs pixels.

On error: isError:true with {"error":"Failed to retrieve mind map","message"}.

Use list_mindmaps first to obtain a valid filePath. Prefer this over regenerating when the file already exists.
- **cleanup_mindmaps** — Permanently delete markmap* files from the output directory. DESTRUCTIVE and irreversible when dryRun is false.

dryRun defaults to false — omitting it WILL delete. Always call once with dryRun=true to preview, then again with dryRun=false to commit. Prefer list_mindmaps beforehand.

Returns {"deleted":["<path>",...],"kept":<n>}; dryRun responses also include dryRun:true and do not delete.

Use instead of manual file deletion when pruning old generated mind maps.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "markmap-mcp-server": {
    "command": "npx",
    "args": ["-y","@jinzcdev/markmap-mcp-server"]
  }
}
```

## Documentation

## 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`:

```bash
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:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/jinzcdev-markmap-mcp-server/readme_