用途
Markmap MCP Server 是一个基于 Model Context Protocol（MCP）的服务端工具，用于将 Markdown 文本转换为交互式思维导图。它利用 markmap 渲染引擎，把 Markdown 中的标题和嵌套列表解析为可视化的思维导图，并可根据配置在服务端导出 PNG、JPG、SVG 图片，便于 Agent 直接消费和传递。
主要能力
- Markdown 转思维导图：将包含标题与嵌套列表的 Markdown 转换为交互式 HTML 思维导图。
- Agent 友好的返回方式：可返回文件路径、内联 HTML 和/或图片内容，具体由启动时的配置决定。
- 服务端导出：通过 Playwright 在服务端导出 PNG / JPG / SVG，方便在聊天或内联中预览。
- 浏览器预览：可配置打开行为，支持 always（总是打开）、never（从不打开）或 agent（由 Agent 决定），该选项在服务器启动时设定。
- 浏览器导出工具栏：查看 HTML 时，可在页面 UI 中直接导出 PNG/JPG/SVG 或复制 Markdown。
- 离线 HTML：启动时加
--offline参数会内联资源，使页面无需 CDN 访问即可工作。 - 文件工作流：支持从 inputPath 读取文件、列出最近生成的输出、清理旧文件。
- 隐私优先：完全本地转换，不使用云端思维导图 API。
使用方式
环境要求
- Node.js v20 或以上版本。
- 如需服务端图片导出（format: png|jpg|svg），需安装 Playwright 和 Chromium。Playwright 是本包的可选依赖。
配置 MCP 客户端
在 MCP 客户端（如 Cursor / Claude Desktop 等）中添加相应配置。也可以克隆仓库并在本地运行。
服务器偏好设置（通过 CLI 或环境变量）
这些设置需要在服务器启动时决定，而不是作为工具参数传入：
- CLI 标志会覆盖环境变量。
--output会覆盖MARKMAP_DIR。 --open：单独使用--open表示 always。也可以传入--open always|never|agent。无效值会导致报错退出。如果不传该标志，则使用环境变量MARKMAP_OPEN（默认值为 never）。- 生成的 HTML 始终包含 markmap 工具栏、英文导出标签和完全展开的节点。
可用工具
markdown_to_mindmap
将 Markdown 转换为交互式思维导图，并可选生成图片。返回内容根据 returnMode 不同：
- returnMode=path：对于图片格式，filePath 是图片路径，htmlFilePath 仍是 HTML 源文件路径。
- returnMode=content：返回原始 HTML 文本块，或针对 png/jpg/svg 返回 MCP 图片内容块（base64），不返回路径 JSON。超过 200KB 的 HTML 会回退为路径 JSON。
- returnMode=both：返回路径 JSON 加上上述的内联内容。
注意：交互式缩放/折叠以及页面内的“Export PNG/JPG/SVG”按钮属于 HTML 查看器的功能。服务端 format 参数（png|jpg|svg）是 Agent 可以直接消费的格式，无需手动点击浏览器。
其他工具
- 列出输出目录中最近生成的文件（按最新优先）。仅包含文件名以 markmap 开头的文件。返回
{outputDir, files: [{name, filePath, size, mtimeMs, mtime}]}。 - 通过绝对路径检索生成的思维导图文件。路径必须位于配置的输出目录内，禁止路径遍历。返回 JSON
{filePath, mimeType, size}。对于小于 200KB 的 HTML/SVG，还会附加一个文本内容块。PNG/JPG 仅返回元数据（不含图片块），如需像素内容请通过 markdown_to_mindmap 并设置 format=png|jpg 重新导出。 - cleanup_mindmaps：删除旧的（或全部）生成的思维导图文件。
- 提示词 mindmap_from_content：一个辅助提示词，要求模型将笔记整理为 Markdown，然后调用 markdown_to_mindmap。
示例提示
- “把这份设计文档总结成思维导图。”
- “将 ./notes/architecture.md 转换为思维导图。”
- “为这份大纲生成一张 PNG 思维导图用于聊天。”
适用场景
- 在 Agent 或聊天机器人的工作流中，将 Markdown 笔记、文档大纲、设计文档等快速转为可视化的思维导图。
- 需要将思维导图以图片形式直接在对话中展示，而无需手动打开浏览器操作。
- 对隐私有要求、希望完全本地转换而不调用云端 API 的场景。
限制
- 需要 Node.js v20 或以上版本。
- 服务端图片导出依赖 Playwright 和 Chromium。
- 预览打开行为和输出方式等设置需在服务器启动时确定，不能作为工具调用参数动态更改。
- 检索文件时路径必须位于配置的输出目录内，不允许路径遍历。
- PNG/JPG 的检索仅返回元数据，不含图片块。
- 本项目基于 MIT 许可证。
