Markmap MCP Server

Markmap MCP 服务

Markmap MCP 服务基于 Model Context Protocol（MCP）。它使用 markmap 将 Markdown 转换为交互式思维导图，并可选择在服务端导出 PNG / JPG / SVG，方便 Agent 使用。生成过程在本地运行，无需第三方 API 密钥。

功能

• Markdown → 思维导图：将 Markdown（标题和嵌套列表）转换为交互式 HTML 思维导图
• 适合 Agent 的返回结果：返回文件路径、内嵌 HTML 和／或图像内容（启动时配置）
• 服务端导出：通过 Playwright 导出 PNG / JPG / SVG，方便在聊天中或内嵌预览
• 浏览器预览：可配置打开方式——始终打开、从不打开或由 Agent 决定（启动时设置）
• 浏览器导出工具栏：查看 HTML 时，还可在页面 UI 中导出 PNG/JPG/SVG 或复制 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 是此软件包的可选依赖项。）

安装

# 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

或者克隆并在本地运行：

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

使用方法

将以下配置添加到 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 / 环境变量）

这些选项在服务启动时确定，不是工具参数：

偏好设置	CLI	环境变量	可选值	默认值
输出目录	--output / -o	MARKMAP_DIR	任意目录路径	~/.markmap-mcp
在浏览器中打开	--open [mode]	MARKMAP_OPEN	always | never | agent（单独使用 --open = always）	never
返回模式	--return-mode	MARKMAP_RETURN_MODE	path | content | both	path
离线 HTML	--offline	MARKMAP_OFFLINE	true | false（CLI：传入 --offline 启用）	false

CLI 标志优先于环境变量。--output 优先于 MARKMAP_DIR。

--open： 单独使用 --open 表示 always。你也可以传入 --open always|never|agent。值无效时会报错退出。不使用该标志时，将采用 MARKMAP_OPEN（默认值为 never）。

返回模式：

模式	含义
path	仅返回路径 JSON（htmlFilePath + filePath）
content	仅返回内嵌内容（原始 HTML 文本或 base64 图像块）——不含路径
both	返回路径 JSON 和内嵌内容

生成的 HTML 始终包含 markmap 工具栏、英文导出标签，并将所有节点完全展开。

示例提示词

• “将这份设计文档总结为思维导图。”
• “将 ./notes/architecture.md 转换为思维导图。”
• “为聊天生成这份大纲的 PNG 思维导图。”

可用工具

markdown_to_mindmap

将 Markdown 转换为交互式思维导图（也可选择生成图像）。

参数	类型	默认值	描述
markdown	string	—	Markdown 内容（除非设置了 inputPath，否则必填）。如果同时提供两者，则以此参数为准。
inputPath	string	—	本地 .md 文件的绝对路径
format	html | png | svg | jpg	html	输出格式。图像格式需要 Playwright
filename	string	auto	输出文件名（会进行清理；必要时添加 markmap- 前缀；重用时会覆盖）
open	boolean	false	是否在浏览器中打开结果。仅当服务端打开模式为 agent 时才会显示（--open agent / MARKMAP_OPEN=agent）。

返回值（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，以及上述内联内容。

**注意：**交互式缩放/折叠和页面内的“导出 PNG/JPG/SVG”按钮属于 HTML 查看器。服务端的 format: png|jpg|svg 可供 Agent 直接使用，无需手动点击浏览器。

list_mindmaps

列出输出目录中最近生成的文件（最新的排在前面）。仅包含名称以 markmap 开头的文件。

参数	类型	默认值	描述
limit	number	20	返回的最大文件数（1–200）

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

get_mindmap

通过绝对路径获取生成的思维导图文件。路径必须位于已配置的输出目录内（禁止路径遍历）。

参数	类型	默认值	描述
filePath	string	—	思维导图文件的绝对路径（HTML 或图像）

返回 JSON {filePath, mimeType, size}。对于小于 200KB 的 HTML/SVG，还会附加一个文本内容块。PNG/JPG 仅返回元数据（不含图像块）——如果需要像素数据，请使用 format=png\|jpg 通过 markdown_to_mindmap 重新导出。

cleanup_mindmaps

删除较旧的（或全部）已生成思维导图文件。

参数	类型	默认值	描述
maxAgeDays	number	7	删除早于指定天数的文件
all	boolean	false	如果为 true，则删除所有 markmap 文件
dryRun	boolean	false	如果为 true，则预览但不删除

提示词：mindmap_from_content

辅助提示词，请求模型将笔记整理为 Markdown，然后调用 markdown_to_mindmap。

参数	类型	默认值	描述
topic	字符串	—	要整理成思维导图的主题或原始笔记

相关项目

项目	描述
MarkXMind Online	在线使用 Markdown 创建 XMind 思维导图。立即试用 →
Obsidian MarkXMind Plugin	在 Obsidian 中将 XMindMark 语法渲染为 XMind 思维导图。

许可证

本项目采用 MIT 许可证。