mindlm-mcp

Convierte texto, páginas web y PDFs en mapas mentales interactivos. Servidor MCP y CLI, sin necesidad de clave API.

Documentación

mindlm-mcp

Convierte texto, páginas web y PDFs en mapas mentales interactivos: un servidor MCP y una herramienta de línea de comandos, sin necesidad de clave API.

mindlm-mcp turning an outline into a mind map

npx -y mindlm-mcp demo

Eso renderiza un ejemplo integrado y lo abre. Un solo archivo HTML, sin paso de compilación, sin cuenta, sin clave.

Tres entradas. Texto plano o Markdown, una página http(s) o un PDF local.
Dos salidas. Un esquema en Markdown que puedes editar y un mapa mental HTML independiente (markmap) que funciona sin conexión: cada script está incrustado.
Cero claves. A través de MCP, el servidor entrega a tu propio modelo un borrador más el texto fuente limpio y le permite escribir el esquema final. Configura tu propia clave API solo si quieres que el servidor llame a un modelo por sí mismo. Consulta Cómo se escribe el esquema.

Documentación y demo en vivo: https://qingchejun.github.io/mindlm-io/ · Código fuente: https://github.com/qingchejun/mindlm-io

Inicio rápido

Cada cliente ejecuta el mismo comando — npx -y mindlm-mcp serve — y no necesita variables de entorno. MINDMAP_OUTPUT_DIR a continuación es opcional; solo decide dónde se guardan los archivos exportados.

Claude Code

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

Limítalo a un proyecto con --scope project y pasa variables de entorno con -e:

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

Compruébalo con claude mcp list, o /mcp dentro de una sesión.

Claude Desktop

Añade esto a claude_desktop_config.json y luego reinicia la aplicación:

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

El mismo bloque va en ~/.cursor/mcp.json (todos los proyectos) o .cursor/mcp.json (un proyecto):

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

Versiones listas para copiar de los tres viven en examples/configs/.

Luego pide un mapa mental en lenguaje natural — "haz un mapa mental de este PDF", "organiza https://example.com/article" — y el cliente elige la herramienta adecuada.

Herramientas

Cuatro herramientas, siempre anunciadas en este orden. Las tres herramientas *_to_mindmap devuelven un esquema en Markdown; export_mindmap convierte un esquema en un archivo HTML. Cada resultado lleva tanto un bloque de texto legible como structuredContent.

`text_to_mindmap`

Esquematiza texto o Markdown que ya tienes: un borrador, notas, una transcripción, un capítulo pegado.

Campo	Tipo	Notas
`text`	string, obligatorio	El contenido a mapear. Limitado por `MINDMAP_MAX_INPUT_CHARS`.
`mode`	`auto` \| `client` \| `llm` \| `heuristic`	Por defecto `auto`.
`title`	string	Título del nodo raíz. Derivado de la fuente si se omite.
`maxDepth`	int 2–6	Niveles incluyendo la raíz. Por defecto 4.
`maxChildren`	int 3–15	Hijos conservados por nodo. Por defecto 8.
`language`	string	p. ej. `"English"`, `"中文"`. Por defecto el idioma de la fuente.
`export`	boolean	También renderiza un archivo HTML y devuelve su ruta.
`outputPath`	string	Dónde va ese archivo.

Entrada:

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

structuredContent (por defecto auto modo sin clave API, es decir, client modo):

{
  "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. …"
}

Con "mode": "heuristic" (o cuando una clave API lo convierte en "llm") el resultado es el mismo menos sourceText y instructions: el esquema es definitivo y listo para exportar.

`url_to_mindmap`

Obtiene una página y esquematiza su contenido principal. El texto del artículo se extrae con Readability; se eliminan navegación, pies de página y material repetitivo. También se eliminan elementos de la página: marcadores de referencia ([1]), enlaces "[editar]", notas sobre el artículo, pies de foto, cajas de navegación y las secciones finales Véase también / Referencias / Notas / Lecturas adicionales / Enlaces externos / Bibliografía, que son listas de enlaces más que contenido. Una URL que sirve un PDF se pasa automáticamente al pipeline de PDF.

Campo	Tipo	Notas
`url`	string, obligatorio	Solo http(s). Se rechazan direcciones privadas y de bucle local.
…		más todas las opciones de `text_to_mindmap`

Entrada:

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

structuredContent añade un bloque source que describe de dónde proviene el texto:

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

Lee un PDF local, usando sus marcadores como esqueleto cuando los tiene. Un PDF almacena líneas posicionadas en lugar de párrafos, por lo que las líneas con ajuste de línea de un párrafo se vuelven a unir antes de dividir las oraciones; de lo contrario, el "imprimir a PDF" de un navegador produciría nodos como "libera oxígeno." en lugar de oraciones completas.

Campo	Tipo	Notas
`path`	string, obligatorio	Ruta a un PDF local. `~` se expande.
`pages`	string	Selección basada en 1: `"1-20"`, `"3"`, `"1-5,9"`. Todas las páginas por defecto.
…		más todas las opciones 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`

Renderiza un esquema en Markdown a un mapa mental HTML independiente. Llama a esto después de que tú (o tu modelo) hayas escrito el esquema. No sobrescribirá un archivo existente a menos que lo pidas.

Campo	Tipo	Notas
`markdown`	string, obligatorio	Una raíz `#` , luego viñetas `##`/`###` y `-`.
`title`	string	Título de la página. Por defecto la raíz del esquema.
`outputPath`	string	Archivo, o un directorio para generar un nombre.
`offline`	boolean	Incrusta cada script. Por defecto `true`.
`toolbar`	boolean	Barra de herramientas de zoom / ajuste / expandir. Por defecto `true`.
`initialExpandLevel`	int −1–6	Niveles expandidos al abrir; `-1` expande todo.
`colorFreezeLevel`	int 0–6	Deja de cambiar el color de la rama por debajo de este nivel.
`maxWidth`	int 0–2000	Ancho máximo de nodo en píxeles; `0` es ilimitado.
`overwrite`	boolean	Reemplaza el archivo si existe. Por defecto `false`.
`returnHtml`	boolean	Incluye todo el documento en el resultado. Por defecto `false`.
`branding`	boolean	Añade un pequeño enlace de pie de página "Hecho con mindlm-mcp". Por defecto `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

El servidor también expone un prompt, mindmap_outline, que devuelve las reglas del esquema (opcionalmente en un language dado) seguidas de una instrucción para llamar a export_mindmap.

Línea de comandos

El mismo pipeline sin un cliente. Sin argumentos y sin terminal adjunto, mindlm-mcp inicia el servidor MCP, que es lo que quiere un cliente 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

Comando	Qué hace
`serve`	Inicia el servidor MCP en stdio.
`demo`	Renderiza el ejemplo integrado (`--no-open` para omitir el navegador).
`text <file>`	Esquematiza un archivo `.txt`/`.md`, o `-` para stdin.
`url <url>`	Obtiene una página y esquematiza su contenido principal.
`pdf <file>`	Esquematiza un PDF local.
`export <outline>`	Renderiza un esquema Markdown existente.
`doctor`	Informa qué está configurado y dónde se escribirán los archivos.

Opciones en los comandos de conversión:

Opción	Significado
`-o, --output <path>`	Escribe aquí. Una ruta `.md` escribe el esquema, `.html` el mapa mental.
`--title <title>`	Título del nodo raíz y título de la página.
`--md`	Imprime el esquema Markdown en stdout.
`--mode <auto\|llm\|heuristic>`	Cómo se escribe el esquema.
`--depth <n>` / `--max-children <n>`	Forma del árbol.
`--lang <language>`	Idioma para las etiquetas de los nodos.
`--provider <anthropic\|openai>` / `--model <name>`	Anula la configuración del LLM.
`--no-offline`	Enlaza activos CDN en lugar de incrustarlos.
`--no-toolbar`	Oculta la barra de herramientas del mapa mental.
`--open`	Abre el resultado en un navegador.
`--overwrite`	Reemplaza el archivo de salida si existe.
`--branding`	Añade el enlace de pie de página "Hecho con mindlm-mcp".
`-q, --quiet`	Solo imprime resultados, sin progreso.
`--env-file <path>`	Carga variables de entorno desde un archivo primero.

Los resultados que un script podría consumir (una ruta de archivo, un esquema) van a stdout; el progreso y los diagnósticos van a stderr. Códigos de salida: 0 ok, 1 error de uso, 2 error de entrada, 3 error de LLM.

También hay una pequeña API programática — textToOutline, urlToOutline, pdfToOutline, renderMindmapHtml, exportMindmap — exportada desde la raíz del paquete.

Cómo se escribe el esquema

Decidir qué pertenece al árbol es la parte difícil, y hay tres formas de hacerlo. Nunca tienes que proporcionar una clave para que esto funcione.

Modo	Cuándo se usa	Qué sucede
`client`	MCP por defecto sin clave	El servidor devuelve un borrador basado en reglas, el texto fuente limpio e instrucciones. El modelo de tu cliente — con el que ya estás hablando — reescribe el esquema y llama a `export_mindmap`. Nada sale de tu máquina excepto lo que el cliente ya ve.
`heuristic`	CLI por defecto sin clave	Solo reglas, sin red: los encabezados se convierten en ramas, las oraciones clasificadas en hojas. Rápido, determinista, sin conexión.
`llm`	Siempre que `ANTHROPIC_API_KEY` o `OPENAI_API_KEY` esté configurado	El servidor llama a ese modelo por sí mismo, a través de `fetch` simple, usando tu clave y tu endpoint. Vuelve al borrador heurístico si la llamada falla.

mode: "auto" (el predeterminado en todas partes) elige la fila que aplica. Siempre puedes forzar uno con mode a través de MCP o --mode en la CLI. Ejecuta mindlm-mcp doctor para ver a cuál auto se resuelve ahora mismo.

No hay ningún servicio alojado detrás de todo esto: sin telemetría, sin comprobación de actualizaciones, sin llamadas a casa.

Configuración

Cada variable es opcional. Copia .env.example a .env y pásalo explícitamente con --env-file .env — nada se carga automáticamente — o configura las variables en el bloque env de tu cliente MCP.

Variable	Predeterminado	Significado
`MINDMAP_OUTPUT_DIR`	`./mindmaps`	Dónde van los archivos HTML exportados. `~` se expande.
`MINDMAP_LLM_PROVIDER`	auto-detectado	`anthropic` o `openai`. Inferido de la clave que esté configurada.
`ANTHROPIC_API_KEY`	—	Cambia `auto` al modo `llm`.
`OPENAI_API_KEY`	—	Igual, para cualquier endpoint compatible con OpenAI.
`OPENAI_BASE_URL`	`https://api.openai.com/v1`	El endpoint usado con `OPENAI_API_KEY`.
`MINDMAP_LLM_MODEL`	`claude-sonnet-5-5` para Anthropic	Nombre del modelo. Obligatorio para endpoints compatibles con OpenAI, donde ningún nombre es portable.
`MINDMAP_ALLOW_PRIVATE_HOSTS`	`false`	Permite que `url_to_mindmap` alcance localhost y redes privadas.
`MINDMAP_MAX_INPUT_CHARS`	`200000`	Límite máximo de caracteres leídos de cualquier entrada.
`MINDMAP_CLIENT_MAX_CHARS`	`60000`	Límite del texto fuente devuelto en modo `client`.

El HTML exportado

Un solo archivo, abrible con doble clic. Por defecto, cada script y hoja de estilo — d3, markmap-view, la barra de herramientas — está incrustado, por lo que el mapa sigue funcionando sin red, en una máquina bloqueada, o cinco años después cuando un CDN haya cambiado. Eso cuesta unos 340 KB por archivo; pasa offline: false (--no-offline) si prefieres enlazar las copias del CDN.

Los plugins de markmap KaTeX y highlight.js están deliberadamente deshabilitados: ambos extraen hojas de estilo de un CDN, lo que rompería silenciosamente una exportación "sin conexión". El HTML sin procesar en el esquema no se renderiza (markdown-it se ejecuta con html: false), por lo que el texto extraído de una página hostil no puede inyectar script en el archivo que abres.

Las exportaciones no llevan atribución por defecto. --branding / branding: true añade una pequeña línea de pie de página si lo quieres.

Limitaciones

Páginas solo JavaScript. url_to_mindmap lee el HTML que envía el servidor. Una aplicación de una sola página que renderiza su contenido en el cliente volverá vacía o casi vacía: copia el texto y usa text_to_mindmap en su lugar. No hay navegador sin interfaz gráfica.
PDFs escaneados. Un PDF necesita una capa de texto real. Los escaneos y las exportaciones solo de imagen se rechazan con un error claro; no hay OCR.
Los documentos largos se truncan, no se dividen en partes, en MINDMAP_MAX_INPUT_CHARS. Usa pages en un PDF largo, o mapea una sección a la vez.
La heurística es un borrador. Clasifica las oraciones por posición y frecuencia de términos. Es estable y rápida, y a veces elegirá la oración incorrecta. Eso es exactamente por lo que existe el modo client.
Muros de pago, inicios de sesión y robots. El buscador no envía cookies y no inicia sesión.

Seguridad

Protección SSRF. url_to_mindmap resuelve el host primero y rechaza rangos de loopback, privados, link-local (incluida la dirección de metadatos de la nube 169.254.169.254), CGNAT y multicast a menos que establezcas MINDMAP_ALLOW_PRIVATE_HOSTS=true. Solo se aceptan http: y https:.
Límites. 5 MB por respuesta obtenida, un tiempo de espera de 15 s, como máximo 5 redirecciones, 50 MB / 300 páginas por PDF y un límite de caracteres en cada entrada.
Sin telemetría, sin verificación de actualizaciones, sin backend alojado. Las únicas llamadas de red son la URL que solicitas y — si tú configuraste una clave — tu propio endpoint de LLM.
Sin HTML sin procesar en las exportaciones, y el JSON integrado tiene </script> escapado.
Informar de una vulnerabilidad y la advertencia conocida sobre el rebinding de DNS: SECURITY.md.

Materiales de lanzamiento y listados de directorios

Esta sección es un marcador de posición propiedad del responsable de divulgación. El texto del anuncio, las entradas de listas impresionantes y los envíos al directorio de MCP (mcp.so, Glama, Smithery, PulseMCP, el Registro oficial de MCP) se rastrean en docs/launch.md y están intencionalmente vacíos aquí.

Contribuciones

Las incidencias y las solicitudes de extracción son bienvenidas: consulta CONTRIBUTING.md. Requiere Node ≥ 22.12.

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

¿Quieres un editor completo?

mindlm-mcp es deliberadamente pequeño: esquema de entrada, un archivo HTML de salida. Si quieres seguir editando el mapa después — arrastrar nodos, reestilizar ramas, colaborar, mantener una biblioteca de mapas — para eso es mindlm.io. Este paquete funciona completamente por sí solo y nunca se comunica con él.

mindlm-mcp

Documentación

mindlm-mcp

Inicio rápido

Claude Code

Claude Desktop

Cursor

Herramientas

text_to_mindmap

url_to_mindmap

pdf_to_mindmap

export_mindmap

Prompt

Línea de comandos

Cómo se escribe el esquema

Configuración

El HTML exportado

Limitaciones

Seguridad

Materiales de lanzamiento y listados de directorios

Contribuciones

¿Quieres un editor completo?

Licencia

`text_to_mindmap`

`url_to_mindmap`

`pdf_to_mindmap`

`export_mindmap`