Same category · Productivity
by jinzcdev · jinzcdev/markmap-mcp-server
Convert Markdown into interactive HTML or server-exported images with documented return modes.
Configure Markmap MCP for Node.js 20+, offline HTML and PNG/JPG/SVG export; diagnose Playwright, output paths and MARKMAP_RETURN_MODE.
Documentation and source review: 2026-10-13. No server or export was run for this guide. GitHub stars: 290 (collected 2026-10-13).
Use Node.js 20 or later. The repository package metadata declares @jinzcdev/markmap-mcp-server version 0.2.0. Merge this author-documented configuration into your MCP client and replace MARKMAP_DIR with an absolute writable directory on the machine running the server.
These preferences are read when the server starts. Restart it after changing them. CLI flags override environment variables; --output overrides MARKMAP_DIR. With no output setting, the default directory is ~/.markmap-mcp.
MARKMAP_OFFLINE=true (or --offline) embeds assets in the HTML so the generated page can work without CDN access. Generating locally does not mean the default HTML is offline: the default offline setting is false.
{
"mcpServers": {
"markmap": {
"command": "npx",
"args": [
"-y",
"@jinzcdev/markmap-mcp-server"
],
"env": {
"MARKMAP_DIR": "/absolute/path/to/mindmaps",
"MARKMAP_OPEN": "never",
"MARKMAP_RETURN_MODE": "both",
"MARKMAP_OFFLINE": "true"
}
}
}
}| Startup preference | Values and behavior |
|---|---|
| MARKMAP_RETURN_MODE | path: paths JSON; content: inline content only; both: paths plus inline content. Default: path. |
| MARKMAP_OPEN | never (default), always, or agent. The tool’s open argument exists only in agent mode. |
| MARKMAP_DIR | Output directory on the server host; a returned path is not a downloadable file on a different machine. |
| MARKMAP_OFFLINE | true embeds assets; false is the default. |
Sources: Markmap README · Package metadata · Checked 2026-10-13.
The following input and path layout illustrate the documented interface; they are not output captured from a running server. Use the same Markdown for the PNG call, change format to png, and keep filename set to release-plan.
With this configuration (return mode both), expect paths JSON plus inline content. The HTML call yields htmlFilePath and filePath pointing to the HTML. The PNG call keeps htmlFilePath for the source and points filePath to the PNG, with an image content block.
Success criterion: the returned HTML opens with Build and Review branches; after image dependencies are ready, the PNG file opens as a nonempty image of the same outline. Paths below are illustrative and use your configured output directory.
{
"markdown": "# Release plan\n\n## Build\n- Tests\n- Production build\n\n## Review\n- Configuration\n- Export files",
"format": "html",
"filename": "release-plan"
}{
"htmlFilePath": "/absolute/path/to/mindmaps/markmap-release-plan.html",
"filePath": "/absolute/path/to/mindmaps/markmap-release-plan.html"
}{
"markdown": "# Release plan\n\n## Build\n- Tests\n- Production build\n\n## Review\n- Configuration\n- Export files",
"format": "png",
"filename": "release-plan"
}{
"htmlFilePath": "/absolute/path/to/mindmaps/markmap-release-plan.html",
"filePath": "/absolute/path/to/mindmaps/markmap-release-plan.png"
}Sources: Markmap README · Checked 2026-10-13.
Opening the HTML gives you an interactive mind map and toolbar buttons for PNG/JPG/SVG export. A person clicking that toolbar is different from an agent requesting an image through the MCP tool.
To return an image to the agent, call markdown_to_mindmap with format set to png, jpg, or svg. Server-side export needs the optional Playwright package and a launchable browser. The author’s documented setup installs Playwright and Chromium; the source first tries installed Chrome and Edge, then bundled Chromium.
Run these dependency commands only on the intended server environment if you choose to enable image export. HTML generation does not require the server-side image-export dependency.
npm install playwright
npx playwright install chromiumSources: Markmap README · Image export source · Checked 2026-10-13.
| Tool | Arguments and result |
|---|---|
| markdown_to_mindmap | markdown or an absolute inputPath to a .md file; markdown wins if both are set. format: html/png/jpg/svg. filename sets a sanitized base name; reusing it overwrites. |
| list_mindmaps | limit: 1–200, default 20. Lists recent output files whose names start with markmap. |
| get_mindmap | filePath must be absolute and inside the output directory. PNG/JPG return metadata, not image pixels. |
| cleanup_mindmaps | maxAgeDays defaults to 7; all deletes all generated files. Use dryRun=true to preview cleanup. |
Sources: Markmap README · Checked 2026-10-13.
The author describes local generation without third-party API keys. Offline HTML is a separate startup option. Generated files contain your Markdown content; choose an output directory appropriate for those notes.
get_mindmap confines retrieval to the configured output directory. cleanup_mindmaps deletes files; use its dryRun option before cleanup. Reusing a filename can overwrite an existing map.
Sources: Markmap README · Checked 2026-10-13.
| Symptom | Check | Success signal |
|---|---|---|
| Server-side image export requires the optional playwright package | Install Playwright in the environment where this server resolves its dependencies, then install Chromium as documented above. | format=png returns an image file rather than a dependency error. |
| Unable to launch a browser for image export | The source tries Chrome, Edge, then Chromium. Ensure Chromium is installed for the server’s execution user. | The export browser launches and a nonempty image is saved. |
| Only paths returned in chat | Set MARKMAP_RETURN_MODE=both or content at startup and restart the server. HTML at or above 200KB falls back to paths JSON. | Inline content is returned for a supported-size result. |
| get_mindmap returns PNG metadata only | This is documented behavior. Re-export with markdown_to_mindmap and format=png or jpg when the client needs pixels. | An image content block is returned when inline return mode is enabled. |
| Browser does not open or open argument is unavailable | never is the default. Use MARKMAP_OPEN=agent to expose the per-call open boolean, or open the returned HTML manually. | The HTML opens on the server machine’s browser. |
| Offline HTML cannot load assets | Set MARKMAP_OFFLINE=true before server startup and generate a new HTML file. | The regenerated file opens without CDN access. |
| Output path is inaccessible | Use an absolute writable MARKMAP_DIR on the server host. Paths do not transfer files to a remote client. | The file exists in that output directory and can be retrieved or transferred intentionally. |
Sources: Markmap README · Image export source · Checked 2026-10-13.