mindlm-mcp

mindlm-mcp

将文本、网页和 PDF 转换为交互式思维导图——既是 MCP 服务，也是命令行 工具，无需 API 密钥。

npx -y mindlm-mcp demo

这会渲染内置示例并打开它。只需一个 HTML 文件，无需构建步骤、账户或密钥。

• 三种输入。 纯文本或 Markdown、http(s) 网页，或本地 PDF。
• 两种输出。 可编辑的 Markdown 大纲，以及可离线使用的独立 HTML 思维导图 (markmap)——所有脚本都内嵌其中。
• 无需密钥。 通过 MCP 使用时，服务会将草稿和清理后的源文本交给你自己的模型， 由模型编写最终大纲。只有在希望服务自行调用模型时，才需要设置自己的 API 密钥。 请参阅大纲的生成方式。

文档和在线演示：https://qingchejun.github.io/mindlm-io/ · 源代码：https://github.com/qingchejun/mindlm-io

---

快速开始

每个客户端都运行同一条命令——npx -y mindlm-mcp serve——且无需环境 变量。下面的 MINDMAP_OUTPUT_DIR 是可选项；它只决定导出文件的保存位置。

Claude Code

claude mcp add mindlm -- npx -y mindlm-mcp serve

使用 --scope project 将其限定为单个项目，并用 -e 传递环境变量：

claude mcp add mindlm -e MINDMAP_OUTPUT_DIR=~/Documents/mindmaps -- npx -y mindlm-mcp serve

运行 claude mcp list 检查，或在会话中运行 /mcp。

Claude Desktop

将以下内容添加到 claude_desktop_config.json，然后重启应用：

{
  "mcpServers": {
    "mindlm": {
      "command": "npx",
      "args": ["-y", "mindlm-mcp", "serve"],
      "env": {
        "MINDMAP_OUTPUT_DIR": "~/Documents/mindmaps"
      }
    }
  }
}

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

Cursor

将相同配置块放入 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：

{
  "mcpServers": {
    "mindlm": {
      "command": "npx",
      "args": ["-y", "mindlm-mcp", "serve"]
    }
  }
}

examples/configs/ 中提供了三种配置的可直接复制版本。

然后用自然语言请求生成思维导图——“为这份 PDF 制作思维导图”、*“梳理 https://example.com/article”*——客户端会选择合适的工具。

---

工具

共有四种工具，始终按此顺序提供。三个 *_to_mindmap 工具会返回 Markdown 大纲；export_mindmap 会将大纲转换为 HTML 文件。每个结果都包含可读文本块和 structuredContent。

text_to_mindmap

整理你已有的大纲文本或 Markdown——草稿、笔记、访谈记录或粘贴的章节。

字段	类型	说明
text	string，必填	要整理的内容。长度上限由 MINDMAP_MAX_INPUT_CHARS 决定。
mode	auto | client | llm | heuristic	默认值为 auto。
title	string	根节点标题。若省略，则根据源内容生成。
maxDepth	int 2–6	包含根节点在内的层级数。默认值为 4。
maxChildren	int 3–15	每个节点保留的子节点数。默认值为 8。
language	string	例如 "English"、"中文"。默认使用源内容的语言。
export	boolean	同时生成 HTML 文件并返回其路径。
outputPath	string	文件保存位置。

输入：

{
  "text": "# Tides\n\nSpring tides are the largest of the month.\n\n## Neap\n\nNeap tides are the smallest.\n"
}

structuredContent（默认的 auto 模式且未设置 API 密钥时，即 client 模式）：

{
  "title": "Tides",
  "markdown": "# Tides\n\n## Spring tides are the largest of the month.\n\n### Neap\n- Neap tides are the smallest.\n",
  "mode": "client",
  "stats": { "inputChars": 79, "nodes": 4, "depth": 4, "truncated": false },
  "sourceText": "# Tides\n\nSpring tides are the largest of the month.\n\n## Neap\n\nNeap tides are the smallest.",
  "instructions": "This is a DRAFT outline produced by a rule-based algorithm. …"
}

使用 "mode": "heuristic"（或设置 API 密钥后变为 "llm"）时，结果与此相同，但不含 sourceText 和 instructions——此时大纲已完成，可直接导出。

url_to_mindmap

抓取网页并梳理其主要内容。文章文本由 Readability 提取；导航、页脚和模板内容会被 剔除。页面中的附属内容也会被移除：引用标记（[1]）、“[edit]”链接、文章上方的注释、图片说明、导航框，以及末尾的 See also / References / Notes / Further reading / External links / Bibliography 等章节，因为它们是链接列表，而非正文。若 URL 指向 PDF，则会自动交由 PDF 流程处理。

字段	类型	说明
url	字符串，必填	仅支持 http(s)。拒绝私有地址和环回地址。
…		以及 text_to_mindmap 的所有选项

输入：

{ "url": "https://example.com/tide-tables", "mode": "heuristic" }

structuredContent 会添加一个 source 区块，说明文本的来源：

{
  "title": "Tide tables",
  "markdown": "# Tide tables\n\n## Spring tides …\n\n## Neap tides …\n",
  "mode": "heuristic",
  "stats": { "inputChars": 1042, "nodes": 9, "depth": 3, "truncated": false },
  "source": {
    "url": "https://example.com/tide-tables",
    "finalUrl": "https://example.com/tide-tables",
    "title": "Tide tables",
    "siteName": "Example",
    "fetchedAt": "2026-09-27T10:21:04.512Z",
    "contentType": "text/html"
  }
}

pdf_to_mindmap

读取本地 PDF；若文件包含书签，则以书签作为骨架。PDF 存储的是带位置的行，而非段落，因此会先重新拼接同一段落中因自动换行而断开的行，再拆分句子——否则，浏览器的“打印为 PDF”可能会生成“释放 氧气。”这样的节点，而不是完整句子。

字段	类型	说明
path	字符串，必填	本地 PDF 的路径。会展开 ~。
pages	字符串	从 1 开始的页码选择，例如 "1-20"、"3"、"1-5,9"。默认选择所有页面。
…		以及 text_to_mindmap 的所有选项

输入：

{ "path": "~/papers/attention.pdf", "pages": "1-12", "mode": "heuristic" }

structuredContent：

{
  "title": "mindlm-mcp PDF fixture",
  "markdown": "# mindlm-mcp PDF fixture\n\n## 1. Introduction\n\n### Mind maps turn a wall of prose into something you can scan…\n",
  "mode": "heuristic",
  "stats": { "inputChars": 769, "nodes": 12, "depth": 4, "truncated": false },
  "source": { "path": "/home/you/papers/attention.pdf", "totalPages": 3, "hasOutline": true }
}

export_mindmap

将 Markdown 大纲渲染为独立的 HTML 思维导图。在你（或你的模型）编写好大纲后调用此工具。除非你明确要求，否则不会覆盖已有文件。

字段	类型	说明
markdown	字符串，必填	一个 # 根节点，后接 ##/### 和 - 项目符号。
title	字符串	页面标题。默认为大纲根节点。
outputPath	字符串	文件路径，或用于生成文件名的目录。
offline	布尔值	内联所有脚本。默认为 true。
toolbar	布尔值	缩放 / 适应 / 展开工具栏。默认为 true。
initialExpandLevel	int −1–6	打开时展开的层级；-1 表示全部展开。
colorFreezeLevel	int 0–6	在此层级以下停止更改分支颜色。
maxWidth	int 0–2000	节点的最大宽度（像素）；0 表示不限制。
overwrite	布尔值	文件已存在时将其替换。默认为 false。
returnHtml	布尔值	在结果中包含完整文档。默认为 false。
branding	布尔值	添加一个简短的“Made with mindlm-mcp”页脚链接。默认为 false。

输入：

{
  "markdown": "# Tides\n\n## Spring\n\n- Sun and moon in line\n\n## Neap\n\n- At right angles\n"
}

structuredContent：

{
  "path": "/home/you/mindmaps/tides-20260927-183322.html",
  "fileUrl": "file:///home/you/mindmaps/tides-20260927-183322.html",
  "bytes": 344349,
  "nodes": 5,
  "offline": true
}

提示词

服务还提供一个提示词 mindmap_outline，其中包含大纲规则（可选使用指定的 language），后接调用 export_mindmap 的指令。

命令行

无需客户端即可运行相同的流水线。不带参数且未连接终端时，mindlm-mcp 会启动 MCP 服务——这正是 MCP 客户端所需要的。

mindlm-mcp demo                                   # render a built-in example and open it
mindlm-mcp text notes.md -o notes.html            # a file, or "-" to read stdin
mindlm-mcp url https://example.com/article --open
mindlm-mcp pdf paper.pdf --pages 1-20
mindlm-mcp export outline.md -o map.html          # an outline you wrote yourself
mindlm-mcp serve                                  # MCP server on stdio
mindlm-mcp doctor                                 # runtime, LLM config, output directory

命令	功能
serve	通过 stdio 启动 MCP 服务。
demo	渲染内置示例（使用 --no-open 可跳过浏览器）。
text <file>	为 .txt/.md 文件生成大纲，或使用 - 从 stdin 读取。
url <url>	获取网页并为其主要内容生成大纲。
pdf <file>	为本地 PDF 生成大纲。
export <outline>	渲染现有的 Markdown 大纲。
doctor	报告当前配置以及文件写入位置。

转换命令的选项：

选项	含义
-o, --output <path>	写入此处。.md 路径用于写入大纲，.html 路径用于写入思维导图。
--title <title>	根节点标题和页面标题。
--md	将 Markdown 大纲打印到 stdout。
--mode <auto|llm|heuristic>	大纲的生成方式。
--depth <n> / --max-children <n>	树的结构。
--lang <language>	节点标签所用的语言。
--provider <anthropic|openai> / --model <name>	覆盖大模型配置。
--no-offline	链接 CDN 资源，而不将其内嵌。
--no-toolbar	隐藏思维导图工具栏。
--open	在浏览器中打开结果。
--overwrite	如果输出文件已存在，则替换它。
--branding	添加 “Made with mindlm-mcp” 页脚链接。
-q, --quiet	仅打印结果，不显示进度。
--env-file <path>	优先从文件加载环境变量。

脚本可能会处理的结果（文件路径、大纲）会输出到 stdout；进度和诊断信息会输出到 stderr。退出代码：0 表示正常，1 表示用法错误，2 表示输入错误，3 表示大模型错误。

此外还提供了一个小型编程 API——textToOutline、urlToOutline、pdfToOutline、 renderMindmapHtml、exportMindmap——从包根目录导出。

---

大纲的生成方式

决定哪些内容应当进入树中是最难的部分，有三种处理方式。要使用这些功能，你无需提供密钥。

模式	使用时机	工作方式
client	无密钥时的 MCP 默认模式	服务返回基于规则的草稿、清理后的源文本和操作说明。客户端使用其模型——也就是你当前正在对话的模型——重写大纲并调用 export_mindmap。除了客户端已经看到的内容，不会有任何数据离开你的设备。
heuristic	无密钥时的 CLI 默认模式	仅使用规则，不访问网络：标题会成为分支，按重要性排序的句子会成为叶节点。快速、确定、离线。
llm	设置了 ANTHROPIC_API_KEY 或 OPENAI_API_KEY 时	服务会使用 你的 密钥和 你的端点，通过普通的 fetch 调用相应模型。如果调用失败，则回退到启发式草稿。

mode: "auto"（所有场景中的默认值）会选择适用的模式。你始终可以通过 MCP 的 mode 或 CLI 的 --mode 强制指定模式。运行 mindlm-mcp doctor，即可查看当前 auto 解析为哪种模式。

上述功能均不依赖托管服务：没有遥测、更新检查，也不会向外发送数据。

配置

所有变量均为可选项。将 .env.example 复制为 .env，并通过 --env-file .env 显式传入——不会自动加载任何内容——或者在 MCP 客户端的 env 块中设置这些变量。

变量	默认值	含义
MINDMAP_OUTPUT_DIR	./mindmaps	导出 HTML 文件的保存位置。~ 会展开。
MINDMAP_LLM_PROVIDER	自动检测	anthropic 或 openai。根据已设置的密钥推断。
ANTHROPIC_API_KEY	—	将 auto 切换为 llm 模式。
OPENAI_API_KEY	—	同上，适用于任何兼容 OpenAI 的端点。
OPENAI_BASE_URL	https://api.openai.com/v1	与 OPENAI_API_KEY 配合使用的端点。
MINDMAP_LLM_MODEL	Anthropic 为 claude-sonnet-5-5	模型名称。对于兼容 OpenAI 的端点，此项为必填，因为没有通用的模型名称。
MINDMAP_ALLOW_PRIVATE_HOSTS	false	允许 url_to_mindmap 访问 localhost 和专用网络。
MINDMAP_MAX_INPUT_CHARS	200000	对从任一输入中读取的字符数设定硬性上限。
MINDMAP_CLIENT_MAX_CHARS	60000	限制 client 模式返回的源文本长度。

导出的 HTML

单个文件，双击即可打开。默认情况下，所有脚本和样式表——d3、markmap-view、工具栏——都会内嵌，因此即使没有网络、在受限设备上，或五年后 CDN 已经迁移，也能正常使用思维导图。每个文件约占 340 KB；如果更愿意链接 CDN 副本，可传入 offline: false（--no-offline）。

特意禁用了 KaTeX 和 highlight.js markmap 插件：它们都会从 CDN 加载样式表，会导致“离线”导出悄然失效。大纲中的原始 HTML 不会被渲染（markdown-it 以 html: false 运行），因此从恶意网页提取的文本无法向你打开的文件中注入脚本。

默认情况下，导出内容不附带署名。如果需要，可使用 --branding / branding: true 添加一行简短页脚。

限制

• 仅支持 JavaScript 的网页。 url_to_mindmap 读取服务器发送的 HTML。客户端渲染内容的单页应用会返回空内容或几乎为空的内容——请复制文本并改用 text_to_mindmap。不提供无头浏览器。
• 扫描版 PDF。 PDF 必须包含真实文本层。扫描件和纯图像导出文件会被拒绝，并显示明确错误；不提供 OCR。
• 长文档会被截断，不会分块，截断上限为 MINDMAP_MAX_INPUT_CHARS。对于较长的 PDF，请使用 pages，或按章节逐次生成思维导图。
• 启发式结果只是草稿。 它根据句子位置和词频为句子排序。它稳定且快速，但有时会选错句子。这正是提供 client 模式的原因。
• 付费墙、登录和 robots 限制。 抓取器不会发送 Cookie，也不会登录。

安全性

• SSRF 防护。 url_to_mindmap 会先解析主机，并拒绝环回、专用、链路本地（包括 169.254.169.254 云元数据地址）、CGNAT 和多播网段，除非你设置 MINDMAP_ALLOW_PRIVATE_HOSTS=true。仅接受 http: 和 https:。
• 限制。 每个抓取响应最多 5 MB，超时时间为 15 秒，最多跟随 5 次重定向；每个 PDF 最多 50 MB / 300 页；每个输入均设有字符数上限。
• 无遥测、无更新检查、无托管后端。 唯一的网络请求是你指定的 URL，以及——如果你配置了密钥——你自己的大模型端点。
• 导出内容不含原始 HTML，内嵌的 JSON 会对 </script> 进行转义。
• 漏洞报告方式及已知的 DNS 重绑定注意事项：SECURITY.md。

---

发布材料和目录列表

本节为占位内容，由外联负责人负责。 公告文案、awesome 列表条目和 MCP 目录提交（mcp.so、Glama、Smithery、PulseMCP、官方 MCP Registry）均在 docs/launch.md 中跟踪，此处有意留空。

贡献

欢迎提交 Issue 和拉取请求——请参阅 CONTRIBUTING.md。需要 Node ≥ 22.12。

npm ci && npm run lint && npm run typecheck && npm test && npm run build

想要功能完整的编辑器？

mindlm-mcp 刻意保持精简：输入大纲，输出一个 HTML 文件。如果你想之后继续编辑思维导图——拖动节点、重新设置分支样式、协作、保存思维导图库——mindlm.io 就是为此而设计的。这个软件包可以完全独立运行，不会与它通信。

许可证

MIT © 2026 青澈君