mindlm-mcp
mindlm-mcp turns text, web pages, and local PDFs into editable Markdown outlines and single-file, offline-capable HTML mind maps — with no API key required.
text_to_mindmap— outline plain text or Markdown you already have (drafts, notes, transcripts).url_to_mindmap— fetch an http(s) page (or hosted PDF), extract main article content with Readability, drop nav/boilerplate, and outline it.pdf_to_mindmap— read a local PDF, preferring its bookmarks as the skeleton; supports page selections like"1-20"or"1-5,9".export_mindmap— render a Markdown outline into one interactive HTML file, with controls for offline inlining, toolbar, expand level, colour freeze level, max width, overwrite, returnHtml, and branding.Three outline strategies via
mode—client(returns a draft plus cleaned source text so your own model writes the final outline),heuristic(fast, rule-based, offline), andllm(server calls Anthropic/OpenAI using your key), withautopicking automatically.Optional inline export — set
export: trueon any*_to_mindmaptool to also write the HTML file and get its path.Shape controls — tune
title,maxDepth(2–6),maxChildren(3–15), andlanguage.Zero-key, no hosted backend — no telemetry or call-home; only the URL you request and your own LLM endpoint if configured.
Safety limits — SSRF guard against private/loopback/metadata addresses, 5 MB fetch cap, timeouts, redirect and PDF page/size limits, input character caps, and no raw HTML in exports.
Also available — an
mindmap_outlineprompt, a matching CLI (demo,text,url,pdf,export,serve,doctor), and a small programmatic API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mindlm-mcp make a mind map from https://example.com/article"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mindlm-mcp
Turn text, web pages and PDFs into interactive mind maps — an MCP server and a command-line tool, with no API key required.

npx -y mindlm-mcp demoThat renders a built-in example and opens it. One HTML file, no build step, no account, no key.
Three inputs. Plain text or Markdown, an http(s) page, or a local PDF.
Two outputs. A Markdown outline you can edit, and a standalone HTML mind map (markmap) that works offline — every script is inlined.
Zero keys. Over MCP the server hands your own model a draft plus the cleaned source text and lets it write the final outline. Set your own API key only if you want the server to call a model itself. See How the outline gets written.
Docs and a live demo: https://qingchejun.github.io/mindlm-io/ · Source: https://github.com/qingchejun/mindlm-io
Quick start
Every client runs the same command — npx -y mindlm-mcp serve — and needs no environment
variables. MINDMAP_OUTPUT_DIR below is optional; it just decides where exported files land.
Claude Code
claude mcp add mindlm -- npx -y mindlm-mcp serveScope it to one project with --scope project, and pass environment variables with -e:
claude mcp add mindlm -e MINDMAP_OUTPUT_DIR=~/Documents/mindmaps -- npx -y mindlm-mcp serveCheck it with claude mcp list, or /mcp inside a session.
Claude Desktop
Add this to claude_desktop_config.json, then restart the app:
{
"mcpServers": {
"mindlm": {
"command": "npx",
"args": ["-y", "mindlm-mcp", "serve"],
"env": {
"MINDMAP_OUTPUT_DIR": "~/Documents/mindmaps"
}
}
}
}macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Cursor
The same block goes in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"mindlm": {
"command": "npx",
"args": ["-y", "mindlm-mcp", "serve"]
}
}
}Ready-to-copy versions of all three live in examples/configs/.
Then ask for a mind map in plain language — "make a mind map of this PDF", "map out https://example.com/article" — and the client picks the right tool.
Related MCP server: gobbler-mcp
Tools
Four tools, always advertised in this order. The three *_to_mindmap tools return a Markdown
outline; export_mindmap turns an outline into an HTML file. Every result carries both a readable
text block and structuredContent.
text_to_mindmap
Outline text or Markdown you already have — a draft, notes, a transcript, a pasted chapter.
Field | Type | Notes |
| string, required | The content to map. Capped by |
|
| Default |
| string | Root node title. Derived from the source if omitted. |
| int 2–6 | Levels including the root. Default 4. |
| int 3–15 | Children kept per node. Default 8. |
| string | e.g. |
| boolean | Also render an HTML file and return its path. |
| string | Where that file goes. |
Input:
{
"text": "# Tides\n\nSpring tides are the largest of the month.\n\n## Neap\n\nNeap tides are the smallest.\n"
}structuredContent (default auto mode with no API key, i.e. client mode):
{
"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. …"
}With "mode": "heuristic" (or when an API key makes it "llm") the result is the same minus
sourceText and instructions — the outline is final and ready to export.
url_to_mindmap
Fetch a page and outline its main content. Article text is extracted with
Readability; navigation, footers and boilerplate are
dropped. Page furniture goes too: reference markers ([1]), "[edit]" links, notes above the
article, image captions, navigation boxes, and the trailing See also / References / Notes /
Further reading / External links / Bibliography sections, which are link lists rather than
content. A URL that serves a PDF is handed to the PDF pipeline automatically.
Field | Type | Notes |
| string, required | http(s) only. Private and loopback addresses are refused. |
… | plus every option from |
Input:
{ "url": "https://example.com/tide-tables", "mode": "heuristic" }structuredContent adds a source block describing where the text came from:
{
"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
Read a local PDF, using its bookmarks as the skeleton when it has them. A PDF stores positioned lines rather than paragraphs, so the soft-wrapped lines of one paragraph are rejoined before sentences are split — otherwise a browser's "print to PDF" would yield nodes like "releases oxygen." instead of whole sentences.
Field | Type | Notes |
| string, required | Path to a local PDF. |
| string | 1-based selection: |
… | plus every option from |
Input:
{ "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
Render a Markdown outline into a standalone HTML mind map. Call this after you (or your model) have written the outline. It will not overwrite an existing file unless you ask.
Field | Type | Notes |
| string, required | One |
| string | Page title. Defaults to the outline root. |
| string | File, or a directory to generate a name in. |
| boolean | Inline every script. Default |
| boolean | Zoom / fit / expand toolbar. Default |
| int −1–6 | Levels expanded on open; |
| int 0–6 | Stop changing branch colour below this level. |
| int 0–2000 | Maximum node width in pixels; |
| boolean | Replace the file if it exists. Default |
| boolean | Include the whole document in the result. Default |
| boolean | Add a small "Made with mindlm-mcp" footer link. Default |
Input:
{
"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
}Prompt
The server also exposes one prompt, mindmap_outline, which returns the outline rules
(optionally in a given language) followed by an instruction to call export_mindmap.
Command line
The same pipeline without a client. With no arguments and no terminal attached, mindlm-mcp
starts the MCP server — which is what an MCP client wants.
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 directoryCommand | What it does |
| Start the MCP server on stdio. |
| Render the built-in example ( |
| Outline a |
| Fetch a page and outline its main content. |
| Outline a local PDF. |
| Render an existing Markdown outline. |
| Report what is configured and where files will be written. |
Options on the conversion commands:
Option | Meaning |
| Write here. A |
| Root node title and page title. |
| Print the Markdown outline to stdout. |
| How the outline is written. |
| Shape of the tree. |
| Language for the node labels. |
| Override the LLM configuration. |
| Link CDN assets instead of inlining them. |
| Hide the mind map toolbar. |
| Open the result in a browser. |
| Replace the output file if it exists. |
| Add the "Made with mindlm-mcp" footer link. |
| Only print results, no progress. |
| Load environment variables from a file first. |
Results a script might consume (a file path, an outline) go to stdout; progress and diagnostics go
to stderr. Exit codes: 0 ok, 1 usage error, 2 input error, 3 LLM error.
There is also a small programmatic API — textToOutline, urlToOutline, pdfToOutline,
renderMindmapHtml, exportMindmap — exported from the package root.
How the outline gets written
Deciding what belongs in the tree is the hard part, and there are three ways to do it. You never have to supply a key for any of this to work.
Mode | When it is used | What happens |
| MCP default with no key | The server returns a rule-based draft, the cleaned source text and instructions. Your client's model — the one you are already talking to — rewrites the outline and calls |
| CLI default with no key | Rules only, no network: headings become branches, ranked sentences become leaves. Fast, deterministic, offline. |
| Whenever | The server calls that model itself, over plain |
mode: "auto" (the default everywhere) picks the row that applies. You can always force one with
mode over MCP or --mode on the CLI. Run mindlm-mcp doctor to see which one auto resolves to
right now.
There is no hosted service behind any of this: no telemetry, no update check, no call home.
Configuration
Every variable is optional. Copy .env.example to .env and pass it explicitly
with --env-file .env — nothing is loaded automatically — or set the variables in your MCP
client's env block.
Variable | Default | Meaning |
|
| Where exported HTML files go. |
| auto-detected |
|
| — | Switches |
| — | Same, for any OpenAI-compatible endpoint. |
|
| The endpoint used with |
|
| Model name. Required for OpenAI-compatible endpoints, where no name is portable. |
|
| Let |
|
| Hard cap on characters read from any one input. |
|
| Cap on the source text returned in |
The exported HTML
One file, openable with a double click. By default every script and stylesheet — d3, markmap-view,
the toolbar — is inlined, so the map keeps working with no network, on a locked-down machine, or
five years from now when a CDN has moved on. That costs about 340 KB per file; pass
offline: false (--no-offline) if you would rather link the CDN copies.
The KaTeX and highlight.js markmap plugins are deliberately disabled: both pull stylesheets from a
CDN, which would quietly break an "offline" export. Raw HTML in the outline is not rendered
(markdown-it runs with html: false), so text extracted from a hostile page cannot inject
script into the file you open.
Exports carry no attribution by default. --branding / branding: true adds one small footer
line if you want it.
Limitations
JavaScript-only pages.
url_to_mindmapreads the HTML the server sends. A single-page app that renders its content client-side will come back empty or nearly so — copy the text and usetext_to_mindmapinstead. There is no headless browser.Scanned PDFs. A PDF needs a real text layer. Scans and image-only exports are rejected with a clear error; there is no OCR.
Long documents are truncated, not chunked, at
MINDMAP_MAX_INPUT_CHARS. Usepageson a long PDF, or map it a section at a time.The heuristic is a draft. It ranks sentences by position and term frequency. It is stable and fast, and it will sometimes pick the wrong sentence. That is exactly why
clientmode exists.Paywalls, logins and robots. The fetcher sends no cookies and does not log in.
Security
SSRF guard.
url_to_mindmapresolves the host first and refuses loopback, private, link-local (including the169.254.169.254cloud metadata address), CGNAT and multicast ranges unless you setMINDMAP_ALLOW_PRIVATE_HOSTS=true. Onlyhttp:andhttps:are accepted.Limits. 5 MB per fetched response, a 15 s timeout, at most 5 redirects, 50 MB / 300 pages per PDF, and a character cap on every input.
No telemetry, no update check, no hosted backend. The only network calls are the URL you ask for and — if you configured a key — your own LLM endpoint.
No raw HTML in exports, and inlined JSON has
</script>escaped.Reporting a vulnerability, and the known DNS-rebinding caveat: SECURITY.md.
Launch materials and directory listings
This section is a placeholder owned by the outreach lead. Announcement copy, awesome-list entries
and MCP directory submissions (mcp.so, Glama, Smithery, PulseMCP, the official MCP Registry) are
tracked in docs/launch.md and are intentionally empty here.
Contributing
Issues and pull requests are welcome — see CONTRIBUTING.md. Requires Node ≥ 22.12.
npm ci && npm run lint && npm run typecheck && npm test && npm run buildWant a full editor?
mindlm-mcp is deliberately small: outline in, one HTML file out. If you want to keep editing the map afterwards — drag nodes around, restyle branches, collaborate, keep a library of maps — that is what mindlm.io is for. This package works completely on its own and never talks to it.
License
MIT © 2026 青澈君
Available Tools
4 toolsexport_mindmapExport a mind mapA
Render a Markdown outline into a standalone HTML mind map — interactive, single file, no network needed. Call this after you have written or refined an outline. Returns the file path; it does not overwrite an existing file unless you ask it to.
Inputs: markdown (required), title, offline, toolbar, +7 more.
pdf_to_mindmapPDF to mind mapARead-only
Read a local PDF and turn it into a mind-map outline, using its bookmarks as the skeleton when it has them. Scanned PDFs with no text layer are rejected — there is no OCR. Use pages to limit long documents.
Inputs: path (required), mode, pages, title, +5 more.
text_to_mindmapText to mind mapARead-only
Turn text or Markdown into a mind-map outline. Use this for content you already have — a draft, notes, a transcript, a chunk of a document. Returns a Markdown outline; pass export: true, or call export_mindmap afterwards, to get an HTML file.
Inputs: text (required), mode, title, export, +4 more.
url_to_mindmapURL to mind mapARead-only
Fetch an http(s) page (or a PDF served over http) and turn its main content into a mind-map outline. Article text is extracted with Readability; navigation and boilerplate are dropped. Pages that render entirely in JavaScript will come back empty — paste the text into text_to_mindmap instead.
Inputs: url (required), mode, title, export, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool maps to a clearly distinct input source (raw text, URL, local PDF) plus one distinct output operation (HTML export). The only mild overlap is url_to_mindmap also accepting remotely-served PDFs, but the descriptions explicitly differentiate remote vs. local handling.
Three tools share a clean {source}_to_mindmap pattern (text/url/pdf), and all four share the 'mindmap' suffix, making the set cohesive. export_mindmap deviates by using a verb_noun form rather than the source_to pattern, a minor inconsistency.
Four tools is compact and each earns its place: three input adapters and one exporter form a coherent pipeline. It leans slightly thin—no redundancy, but little room for edge operations—so not quite ideal.
The surface covers the core lifecycle: acquire content from text/URL/PDF, produce an outline, and render standalone HTML. Gaps are minor—no import of an existing outline file and no alternative export formats (PNG/SVG/OPML)—but agents can work around them.
Maintenance
Related MCP Connectors
Turn outlines and hierarchical notes into interactive mind maps through a hosted remote MCP server.
Turns an outline or a plan into a clean mind map you can print or download.
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
Convert files, URLs, and documents to clean, AI-ready Markdown via MCP.
Related MCP Servers
- AlicenseAqualityCmaintenanceA Model Context Protocol server that converts Markdown text to interactive mind maps with support for rich interactive operations and multi-format exports.1122 npm290MIT
- AlicenseNot gradedqualityBmaintenanceConverts YouTube videos, audio, documents, and web pages to clean markdown with YAML frontmatter, providing AI assistants with structured content via the MCP protocol.5MIT
- AlicenseAqualityCmaintenanceConverts documents, web pages, media, and more to Markdown via an MCP server with tools for conversion, inspection, vault capture, and format listing, all running locally with privacy-first design.51MIT
- AlicenseNot gradedqualityCmaintenanceMCP server that turns a Markdown folder (e.g. Obsidian vault) into a second brain, capturing readings and ideas, connecting them as concepts, and resurfacing related notes on demand.34 npmMIT