Mindlm MCP

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 demo

That 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 serve

Scope 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 serve

Check 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.json
• Windows: %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.

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.

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.

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.

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.

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 directory

Options on the conversion commands:

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: "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 b