mindlm-mcp

Transforme textos, páginas da web e PDFs em mapas mentais interativos. Servidor MCP e CLI, sem necessidade de chave de API.

GitHub

Documentação

mindlm-mcp

Transforme textos, páginas da web e PDFs em mapas mentais interativos — um servidor MCP e uma ferramenta de linha de comando, sem necessidade de chave de API.

mindlm-mcp turning an outline into a mind map

npx -y mindlm-mcp demo

Isso renderiza um exemplo integrado e o abre. Um único arquivo HTML, sem etapa de build, sem conta, sem chave.

Três entradas. Texto simples ou Markdown, uma página http(s) ou um PDF local.
Duas saídas. Um esboço em Markdown que você pode editar e um mapa mental HTML autônomo (markmap) que funciona offline — todos os scripts estão embutidos.
Zero chaves. Pelo MCP, o servidor entrega ao seu próprio modelo um rascunho, além do texto-fonte limpo, e permite que ele escreva o esboço final. Defina sua própria chave de API somente se quiser que o servidor chame um modelo por conta própria. Veja Como o esboço é escrito.

Documentação e demonstração ao vivo: https://qingchejun.github.io/mindlm-io/ · Código-fonte: https://github.com/qingchejun/mindlm-io

Início rápido

Todo cliente executa o mesmo comando — npx -y mindlm-mcp serve — e não precisa de variáveis de ambiente. MINDMAP_OUTPUT_DIR abaixo é opcional; ele apenas decide onde os arquivos exportados serão salvos.

Claude Code

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

Escopo-o para um único projeto com --scope project e passe variáveis de ambiente com -e:

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

Verifique com claude mcp list ou /mcp dentro de uma sessão.

Claude Desktop

Adicione isto a claude_desktop_config.json e reinicie o aplicativo:

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

O mesmo bloco vai em ~/.cursor/mcp.json (todos os projetos) ou .cursor/mcp.json (um projeto):

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

Versões prontas para copiar de todos os três estão em examples/configs/.

Depois, peça um mapa mental em linguagem natural — "faça um mapa mental deste PDF", "mapeie https://example.com/article" — e o cliente escolhe a ferramenta certa.

Ferramentas

Quatro ferramentas, sempre anunciadas nesta ordem. As três ferramentas *_to_mindmap retornam um esboço em Markdown; export_mindmap transforma um esboço em um arquivo HTML. Cada resultado traz tanto um bloco de texto legível quanto structuredContent.

`text_to_mindmap`

Esboce texto ou Markdown que você já possui — um rascunho, anotações, uma transcrição, um capítulo colado.

Campo	Tipo	Observações
`text`	string, obrigatório	O conteúdo a ser mapeado. Limitado por `MINDMAP_MAX_INPUT_CHARS`.
`mode`	`auto` \| `client` \| `llm` \| `heuristic`	Padrão `auto`.
`title`	string	Título do nó raiz. Derivado da fonte se omitido.
`maxDepth`	int 2–6	Níveis, incluindo a raiz. Padrão 4.
`maxChildren`	int 3–15	Filhos mantidos por nó. Padrão 8.
`language`	string	Ex.: `"English"`, `"中文"`. Padrão: idioma da fonte.
`export`	boolean	Também renderiza um arquivo HTML e retorna seu caminho.
`outputPath`	string	Onde esse arquivo será salvo.

Entrada:

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

structuredContent (padrão auto sem chave de API, ou seja, modo 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. …"
}

Com "mode": "heuristic" (ou quando uma chave de API o torna "llm"), o resultado é o mesmo, menos sourceText e instructions — o esboço é final e pronto para exportar.

`url_to_mindmap`

Busque uma página e esboce seu conteúdo principal. O texto do artigo é extraído com Readability; navegação, rodapés e conteúdo repetitivo são removidos. Elementos de página também são descartados: marcadores de referência ([1]), links "[editar]", notas acima do artigo, legendas de imagens, caixas de navegação e as seções finais Ver também / Referências / Notas / Leitura adicional / Links externos / Bibliografia, que são listas de links em vez de conteúdo. Uma URL que serve um PDF é encaminhada automaticamente ao pipeline de PDF.

Campo	Tipo	Observações
`url`	string, obrigatório	Apenas http(s). Endereços privados e de loopback são recusados.
…		mais todas as opções de `text_to_mindmap`

Entrada:

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

structuredContent adiciona um bloco source descrevendo de onde o texto veio:

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

Leia um PDF local, usando seus marcadores como estrutura quando existirem. Um PDF armazena linhas posicionadas em vez de parágrafos, então as linhas com quebra suave de um parágrafo são reunidas antes de as frases serem divididas — caso contrário, um "imprimir em PDF" do navegador geraria nós como "libera oxigênio." em vez de frases completas.

Campo	Tipo	Observações
`path`	string, obrigatório	Caminho para um PDF local. `~` é expandido.
`pages`	string	Seleção baseada em 1: `"1-20"`, `"3"`, `"1-5,9"`. Todas as páginas por padrão.
…		mais todas as opções de `text_to_mindmap`

Entrada:

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

Renderize um esboço em Markdown em um mapa mental HTML autônomo. Chame isto depois que você (ou seu modelo) tiver escrito o esboço. Não sobrescreverá um arquivo existente, a menos que você peça.

Campo	Tipo	Observações
`markdown`	string, obrigatório	Uma raiz `#` , depois marcadores `##`/`###` e `-`.
`title`	string	Título da página. Padrão: raiz do esboço.
`outputPath`	string	Arquivo, ou um diretório para gerar um nome.
`offline`	boolean	Embutir todos os scripts. Padrão `true`.
`toolbar`	boolean	Barra de ferramentas de zoom / ajustar / expandir. Padrão `true`.
`initialExpandLevel`	int −1–6	Níveis expandidos ao abrir; `-1` expande tudo.
`colorFreezeLevel`	int 0–6	Parar de mudar a cor do ramo abaixo deste nível.
`maxWidth`	int 0–2000	Largura máxima do nó em pixels; `0` é ilimitado.
`overwrite`	boolean	Substituir o arquivo se existir. Padrão `false`.
`returnHtml`	boolean	Incluir o documento inteiro no resultado. Padrão `false`.
`branding`	boolean	Adicionar um pequeno link de rodapé "Feito com mindlm-mcp". Padrão `false`.

Entrada:

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

O servidor também expõe um prompt, mindmap_outline, que retorna as regras de esboço (opcionalmente em um language específico) seguidas de uma instrução para chamar export_mindmap.

Linha de comando

O mesmo pipeline sem um cliente. Sem argumentos e sem terminal anexado, mindlm-mcp inicia o servidor MCP — que é o que um cliente MCP deseja.

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

Comando	O que faz
`serve`	Inicia o servidor MCP em stdio.
`demo`	Renderiza o exemplo integrado (`--no-open` para pular o navegador).
`text <file>`	Esboça um arquivo `.txt`/`.md`, ou `-` para stdin.
`url <url>`	Busca uma página e esboça seu conteúdo principal.
`pdf <file>`	Esboça um PDF local.
`export <outline>`	Renderiza um esboço Markdown existente.
`doctor`	Informa o que está configurado e onde os arquivos serão gravados.

Opções nos comandos de conversão:

Opção	Significado
`-o, --output <path>`	Gravar aqui. Um caminho `.md` grava o esboço, `.html` o mapa mental.
`--title <title>`	Título do nó raiz e título da página.
`--md`	Imprime o esboço em Markdown no stdout.
`--mode <auto\|llm\|heuristic>`	Como o esboço é escrito.
`--depth <n>` / `--max-children <n>`	Forma da árvore.
`--lang <language>`	Idioma dos rótulos dos nós.
`--provider <anthropic\|openai>` / `--model <name>`	Substituir a configuração do LLM.
`--no-offline`	Vincular ativos de CDN em vez de embuti-los.
`--no-toolbar`	Ocultar a barra de ferramentas do mapa mental.
`--open`	Abrir o resultado em um navegador.
`--overwrite`	Substituir o arquivo de saída se existir.
`--branding`	Adicionar o link de rodapé "Feito com mindlm-mcp".
`-q, --quiet`	Apenas imprimir resultados, sem progresso.
`--env-file <path>`	Carregar variáveis de ambiente de um arquivo primeiro.

Resultados que um script pode consumir (um caminho de arquivo, um esboço) vão para stdout; progresso e diagnósticos vão para stderr. Códigos de saída: 0 ok, 1 erro de uso, 2 erro de entrada, 3 erro de LLM.

Há também uma pequena API programática — textToOutline, urlToOutline, pdfToOutline, renderMindmapHtml, exportMindmap — exportada da raiz do pacote.

Como o esboço é escrito

Decidir o que pertence à árvore é a parte difícil, e há três maneiras de fazer isso. Você nunca precisa fornecer uma chave para que nada disso funcione.

Modo	Quando é usado	O que acontece
`client`	Padrão MCP sem chave	O servidor retorna um rascunho baseado em regras, o texto-fonte limpo e instruções. O modelo do seu cliente — aquele com o qual você já está conversando — reescreve o esboço e chama `export_mindmap`. Nada sai da sua máquina, exceto o que o cliente já vê.
`heuristic`	Padrão CLI sem chave	Apenas regras, sem rede: cabeçalhos viram ramos, frases classificadas viram folhas. Rápido, determinístico, offline.
`llm`	Sempre que `ANTHROPIC_API_KEY` ou `OPENAI_API_KEY` estiver definido	O servidor chama esse modelo diretamente, via `fetch` simples, usando sua chave e seu endpoint. Volta ao rascunho heurístico se a chamada falhar.

mode: "auto" (o padrão em todos os lugares) escolhe a linha que se aplica. Você sempre pode forçar um com mode via MCP ou --mode na CLI. Execute mindlm-mcp doctor para ver qual auto resolve agora.

Não há serviço hospedado por trás de nada disso: sem telemetria, sem verificação de atualização, sem chamada para casa.

Configuração

Toda variável é opcional. Copie .env.example para .env e passe-o explicitamente com --env-file .env — nada é carregado automaticamente — ou defina as variáveis no bloco env do seu cliente MCP.

Variável	Padrão	Significado
`MINDMAP_OUTPUT_DIR`	`./mindmaps`	Onde os arquivos HTML exportados vão. `~` é expandido.
`MINDMAP_LLM_PROVIDER`	detectado automaticamente	`anthropic` ou `openai`. Inferido de qual chave está definida.
`ANTHROPIC_API_KEY`	—	Alterna `auto` para o modo `llm`.
`OPENAI_API_KEY`	—	O mesmo, para qualquer endpoint compatível com OpenAI.
`OPENAI_BASE_URL`	`https://api.openai.com/v1`	O endpoint usado com `OPENAI_API_KEY`.
`MINDMAP_LLM_MODEL`	`claude-sonnet-5-5` para Anthropic	Nome do modelo. Obrigatório para endpoints compatíveis com OpenAI, onde nenhum nome é portátil.
`MINDMAP_ALLOW_PRIVATE_HOSTS`	`false`	Permite que `url_to_mindmap` alcance localhost e redes privadas.
`MINDMAP_MAX_INPUT_CHARS`	`200000`	Limite rígido de caracteres lidos de qualquer entrada.
`MINDMAP_CLIENT_MAX_CHARS`	`60000`	Limite do texto-fonte retornado no modo `client`.

O HTML exportado

Um único arquivo, abrível com um clique duplo. Por padrão, todos os scripts e folhas de estilo — d3, markmap-view, a barra de ferramentas — são embutidos, então o mapa continua funcionando sem rede, em uma máquina bloqueada ou daqui a cinco anos, quando um CDN tiver mudado. Isso custa cerca de 340 KB por arquivo; passe offline: false (--no-offline) se preferir vincular as cópias do CDN.

Os plugins KaTeX e highlight.js do markmap são deliberadamente desativados: ambos puxam folhas de estilo de um CDN, o que quebraria silenciosamente uma exportação "offline". HTML bruto no esboço não é renderizado (markdown-it roda com html: false), então texto extraído de uma página hostil não pode injetar script no arquivo que você abre.

As exportações não trazem atribuição por padrão. --branding / branding: true adiciona uma pequena linha de rodapé se você quiser.

Limitações

Páginas somente em JavaScript. url_to_mindmap lê o HTML que o servidor envia. Um aplicativo de página única que renderiza seu conteúdo no lado do cliente voltará vazio ou quase vazio — copie o texto e use text_to_mindmap em vez disso. Não há navegador headless.
PDFs escaneados. Um PDF precisa de uma camada de texto real. Digitalizações e exportações somente com imagem são rejeitadas com um erro claro; não há OCR.
Documentos longos são truncados, não divididos em partes, em MINDMAP_MAX_INPUT_CHARS. Use pages em um PDF longo, ou mapeie-o seção por seção.
A heurística é um rascunho. Ela classifica frases por posição e frequência de termos. É estável e rápida, e às vezes escolherá a frase errada. É exatamente por isso que o modo client existe.
Paywalls, logins e robôs. O buscador não envia cookies e não faz login.

Segurança

Proteção SSRF. url_to_mindmap resolve o host primeiro e recusa loopback, privado, link-local (incluindo o endereço de metadados da nuvem 169.254.169.254), CGNAT e faixas multicast, a menos que você defina MINDMAP_ALLOW_PRIVATE_HOSTS=true. Apenas http: e https: são aceitos.
Limites. 5 MB por resposta buscada, um tempo limite de 15 s, no máximo 5 redirecionamentos, 50 MB / 300 páginas por PDF e um limite de caracteres em cada entrada.
Sem telemetria, sem verificação de atualização, sem backend hospedado. As únicas chamadas de rede são a URL que você solicita e — se você configurou uma chave — seu próprio endpoint de LLM.
Sem HTML bruto nas exportações, e JSON embutido tem </script> escapado.
Relatando uma vulnerabilidade e a ressalva conhecida de rebinding de DNS: SECURITY.md.

Materiais de lançamento e listagens de diretórios

Esta seção é um espaço reservado de propriedade do líder de divulgação. Texto de anúncio, entradas de listas incríveis e envios de diretórios MCP (mcp.so, Glama, Smithery, PulseMCP, o Registro MCP oficial) são rastreados em docs/launch.md e estão intencionalmente vazios aqui.

Contribuindo

Issues e pull requests são bem-vindos — veja CONTRIBUTING.md. Requer Node ≥ 22.12.

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

Quer um editor completo?

mindlm-mcp é deliberadamente pequeno: esboço de entrada, um arquivo HTML de saída. Se você quiser continuar editando o mapa depois — arrastar nós, reestilizar ramos, colaborar, manter uma biblioteca de mapas — isso é para o que mindlm.io serve. Este pacote funciona completamente por conta própria e nunca fala com ele.

mindlm-mcp

Documentação

mindlm-mcp

Início rápido

Claude Code

Claude Desktop

Cursor

Ferramentas

text_to_mindmap

url_to_mindmap

pdf_to_mindmap

export_mindmap

Prompt

Linha de comando

Como o esboço é escrito

Configuração

O HTML exportado

Limitações

Segurança

Materiais de lançamento e listagens de diretórios

Contribuindo

Quer um editor completo?

Licença

`text_to_mindmap`

`url_to_mindmap`

`pdf_to_mindmap`

`export_mindmap`