Markmap MCP 服务器

Markmap MCP Server 基于 模型上下文协议 (MCP)，使用开源项目 markmap 将 Markdown 转为交互式思维导图，并支持在服务端导出 PNG / JPG / SVG，便于 Agent 在对话中直接消费。转换过程在本地完成，无需第三方 API Key。

特性

• Markdown 转思维导图：标题与嵌套列表 → 交互式 HTML 导图
• Agent 友好返回：可返回文件路径、内联 HTML 和/或图片内容（启动时配置）
• 服务端导出：通过 Playwright 导出 PNG / JPG / SVG，供聊天内预览
• 浏览器预览：可配置的打开行为 — 始终打开、始终不打开、或由 Agent 决策（启动时配置）
• 页面导出工具栏：在浏览器中也可一键导出图片或复制 Markdown
• 离线 HTML：启动参数 --offline 内联资源，无需访问 CDN
• 文件工作流：支持 inputPath、列出近期文件、清理旧文件
• 隐私优先：纯本地生成，无云端导图 API

前提条件

1. Node.js v20 或以上
2. 使用服务端图片导出（format: png|jpg|svg）时需安装 Playwright 与 Chromium：

npm install playwright
npx playwright install chromium

（playwright 为本包的可选依赖。）

安装

# 从 npm 安装
npm install @jinzcdev/markmap-mcp-server -g

# 基本运行
npx -y @jinzcdev/markmap-mcp-server

# 指定输出目录并自动打开浏览器
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

或克隆仓库本地运行：

git clone https://github.com/jinzcdev/markmap-mcp-server.git
cd markmap-mcp-server
npm install && npm run build
# 可选：启用服务端图片导出
npx playwright install chromium
node build/index.js

使用方法

将以下配置添加到 MCP 客户端（Cursor / Claude Desktop 等）：

{
  "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"
      }
    }
  }
}

服务启动偏好（CLI / 环境变量）

以下选项在服务启动时决定，不是工具入参：

命令行参数优先于环境变量；--output 优先于 MARKMAP_DIR。

--open： 裸写 --open 等同于 always；也可显式传 --open always|never|agent。非法值会报错退出。未写 flag 时使用 MARKMAP_OPEN（默认 never）。

返回模式：

生成的 HTML 固定包含 markmap 工具栏、英文导出按钮文案，并默认展开全部节点。

示例提示词

• 「把这篇设计文档整理成思维导图。」
• 「将 ./notes/architecture.md 转成导图。」
• 「根据下面大纲生成 PNG 思维导图，直接在对话里展示。」

可用工具

markdown_to_mindmap

将 Markdown 转为交互式思维导图（可选导出图片）。

返回值（returnMode=path）：

{
  "htmlFilePath": "/path/to/markmap-….html",
  "filePath": "/path/to/markmap-….html"
}

图片格式下 filePath 为图片路径，htmlFilePath 仍为 HTML 源文件。

返回值（returnMode=content）： 原始 HTML 文本块，或 PNG/JPG/SVG 的 MCP image（base64）内容块 — 不含路径 JSON。HTML ≥200KB 时回退为路径 JSON。

返回值（returnMode=both）： 路径 JSON + 上述内联内容。

说明： 页面内的缩放/折叠与「Export PNG/JPG/SVG」按钮属于 HTML 预览体验。Agent 若要直接拿到图片，请使用工具参数 format: png|jpg|svg。

list_mindmaps

列出输出目录中近期生成的导图文件（最新优先）。仅包含文件名以 markmap 开头的文件。

返回 {outputDir, files: [{name, filePath, size, mtimeMs, mtime}]}。

get_mindmap

按绝对路径获取已生成的导图文件。路径必须位于配置的输出目录内（禁止路径穿越）。

返回 JSON {filePath, mimeType, size}。HTML/SVG 且小于 200KB 时另附文本内容块；PNG/JPG 仅返回元数据（无 image 块）— 需要像素时请用 markdown_to_mindmap 的 format=png|jpg 重新导出。

cleanup_mindmaps

按天数清理（或清空）输出目录中的导图文件。

Prompt：mindmap_from_content

辅助 Prompt：先将内容整理为层级 Markdown，再调用 markdown_to_mindmap。

相关项目

许可证

本项目采用 MIT 许可证。