XMind MCP

xmind-mcp

Un servidor MCP (Model Context Protocol) para leer y escribir archivos locales de mapas mentales XMind. XMind MCP expone 27 herramientas que permiten a cualquier cliente de IA compatible con MCP crear, navegar y editar archivos .xmind directamente en disco.

---

Requisitos previos

Compilación

• Go 1.26.1 o posterior

Uso

• Cualquier cliente compatible con MCP (Claude Desktop, Cursor, etc.)

---

Instalación

Usando go install (recomendado)

go install github.com/mab-go/xmind-mcp/cmd/xmind-mcp@latest

Esto obtiene, compila e instala el binario en un solo paso. No se requiere clonar el repositorio.

Compilar desde el código fuente

git clone https://github.com/mab-go/xmind-mcp.git
cd xmind-mcp
make build

El binario se escribe en ./bin/xmind-mcp con metadatos de versión de git (consulta el objetivo build en el Makefile). Un simple go build ./cmd/xmind-mcp también funciona pero omite esos ldflags.

Nota: Se publica una imagen de contenedor multiplataforma en GHCR en cada push a main y en etiquetas de versión (consulta Docker a continuación). Los binarios precompilados para Linux y Windows se adjuntan a cada GitHub Release etiquetado.

---

Docker

La imagen ghcr.io/mab-go/xmind-mcp ejecuta el mismo servidor MCP stdio que el binario del host. Monta un directorio del host que contenga tus archivos .xmind y pasa las rutas tal como se ven dentro del contenedor a las herramientas (por ejemplo, si montas /home/you/maps en /maps, usa /maps/my-map.xmind en las llamadas a las herramientas).

Compila y carga localmente (plataforma única):

docker buildx build --platform linux/amd64 --load -t xmind-mcp:test .

Argumentos de compilación opcionales (los valores predeterminados coinciden con una compilación local sin git en contexto):

docker buildx build \
  --platform linux/amd64 \
  --load \
  --build-arg VERSION="$(git describe --tags --always --dirty 2>/dev/null || echo dev)" \
  --build-arg COMMIT="$(git rev-parse HEAD 2>/dev/null || echo unknown)" \
  --build-arg DATE="$(date -u +%Y-%m-%d)" \
  -t xmind-mcp:test .

Compilación multiplataforma (sin --load; adecuada para CI o push a un registro):

docker buildx build --platform linux/amd64,linux/arm64 .

Linux (host amd64): Compilar la variante linux/arm64 ejecuta pasos RUN dentro de una imagen ARM. Sin emulación de usuario QEMU, esos pasos fallan con exec format error. Instala los manejadores binfmt una vez:

docker run --privileged --rm tonistiigi/binfmt --install all

Docker Desktop en macOS y Windows generalmente incluye esto. Si solo necesitas verificar que el Dockerfile se compile en tu máquina, usa solo linux/amd64 (el primer comando anterior).

Ejecuta de forma interactiva (stdio requiere -i):

docker run --rm -i -v /path/on/host:/maps xmind-mcp:test --version

Configuración del cliente MCP (Docker)

Para Claude Desktop, ejecuta la imagen publicada mediante docker y pasa los montajes en args (ajusta la ruta del host). Ejemplo de claude_desktop_config.json:

{
  "mcpServers": {
    "xmind": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/on/host:/maps",
        "ghcr.io/mab-go/xmind-mcp:latest"
      ]
    }
  }
}

---

Configuración del cliente MCP

Agrega lo siguiente al archivo de configuración de tu cliente MCP. Para Claude Desktop, eso es claude_desktop_config.json:

{
  "mcpServers": {
    "xmind": {
      "command": "xmind-mcp"
    }
  }
}

Si compilaste desde el código fuente o el binario no está en tu PATH, usa la ruta completa al binario:

{
  "mcpServers": {
    "xmind": {
      "command": "/absolute/path/to/xmind-mcp"
    }
  }
}

Nivel de registro

El servidor registra en el error estándar en el nivel info de forma predeterminada. Para cambiarlo, pasa la bandera --log-level o establece la variable de entorno XMIND_MCP_LOG_LEVEL (la bandera gana si ambos están establecidos). Los valores aceptados son debug, info, warn y error; un valor no reconocido sale con un error al inicio.

Si un manejador de herramienta entra en pánico, el servidor sigue ejecutándose: devuelve un error interno al cliente y registra una línea tool.panic de nivel error con un seguimiento de pila, independientemente del nivel de registro.

debug agrega detalles de ciclo de vida por conexión: el nombre del cliente y la versión del protocolo MCP, registrados en el protocolo de initialize o, para clientes en el protocolo 2026-07-28, en server/discover. Para habilitarlo desde una configuración de cliente, establécelo mediante env:

{
  "mcpServers": {
    "xmind": {
      "command": "xmind-mcp",
      "env": { "XMIND_MCP_LOG_LEVEL": "debug" }
    }
  }
}

---

Herramientas

Todas las herramientas tienen el prefijo xmind_ para evitar colisiones en entornos con múltiples servidores. Cada herramienta también lleva anotaciones MCP (un título de visualización más sugerencias de solo lectura, destructivas e idempotentes), para que los clientes puedan aprobar automáticamente las lecturas y preguntar antes de ediciones destructivas. El servidor también envía instrucciones breves de uso cuando un cliente se conecta; los clientes que las admiten las agregan al contexto del modelo. Las herramientas que devuelven JSON también declaran un esquema de salida y devuelven los mismos datos como structuredContent, para que los clientes que admiten MCP salida estructurada puedan usarlos sin analizar texto.

Nivel 1: Gestión de archivos y hojas

Herramienta	Descripción
xmind_open_map	Analiza un archivo .xmind y devuelve un resumen estructural (nombres de hojas, temas raíz, recuentos de nodos).
xmind_list_sheets	Devuelve los nombres e IDs de todas las hojas en un libro de trabajo.
xmind_create_map	Crea un nuevo archivo .xmind con una sola hoja y tema raíz.
xmind_add_sheet	Agrega una nueva hoja a un libro de trabajo existente.
xmind_delete_sheet	Elimina una hoja de un libro de trabajo.
xmind_list_relationships	Lista todas las relaciones en una hoja (IDs de extremos y títulos de temas como JSON).

Nivel 2: Encontrar temas

Usa estas herramientas para resolver IDs y títulos de temas antes de editar una rama específica del árbol. Algunas herramientas de escritura en su lugar necesitan IDs a nivel de hoja o IDs de xmind_list_relationships—consulta la descripción de cada herramienta.

Herramienta	Descripción
xmind_get_subtree	Devuelve la jerarquía completa de temas con raíz en un tema dado (o toda la hoja); los temas flotantes y de resumen se marcan con childType.
xmind_get_topic_properties	Devuelve los metadatos de un tema como JSON (notas, marcadores, límites, relaciones de hoja para ese tema, recuentos de hijos); úsalo para verificar escrituras.
xmind_search_topics	Busca temas por palabra clave; devuelve coincidencias con IDs, ancestryPath (títulos desde la raíz de la hoja hasta el padre de la coincidencia, o null en la raíz de la hoja), título del padre, profundidad, childType y campos de hoja al buscar en todas las hojas.
xmind_find_topic	Encuentra un solo tema por título exacto; devuelve ID, ancestryPath (cadena desde la raíz de la hoja hasta el padre de la coincidencia; null en la raíz de la hoja; no relativo al ámbito de parent_id), más contexto de padre/hermano relativo al ámbito de búsqueda.

Nivel 3: Mutaciones de temas

La mayoría de las herramientas aquí apuntan a un tema y toman un topic_id del Nivel 2 (o de resultados anteriores). Algunas usan otros IDs (from_id/to_id, relationship_id, etc.)—consulta cada fila.

En caso de éxito, xmind_add_topic, xmind_add_topics_bulk, xmind_duplicate_topic y xmind_move_topic devuelven JSON (IDs de temas, índices de inserción, recuentos de hermanos y campos relacionados). Las claves exactas coinciden con la descripción de cada herramienta del servidor MCP en ejecución. Otras herramientas de mutación en este nivel devuelven mensajes de éxito en texto plano a menos que sus descripciones indiquen lo contrario.

Herramienta	Descripción
xmind_add_topic	Agrega un hijo bajo un padre; notas, etiquetas, marcadores, enlace, remove_markers opcionales (mismas reglas que xmind_set_topic_properties); el cuerpo de éxito es JSON.
xmind_add_topics_bulk	Agrega muchos temas (planos o anidados); cada objeto puede establecer los mismos campos de metadatos opcionales; el cuerpo de éxito es JSON.
xmind_duplicate_topic	Clona en profundidad un subárbol de temas bajo otro padre (misma hoja); las relaciones de hoja no se copian; el cuerpo de éxito es JSON.
xmind_rename_topic	Cambia el título de un tema existente.
xmind_delete_topic	Elimina un tema y todos sus descendientes.
xmind_move_topic	Mueve un tema (y su subárbol) a un nuevo padre; position opcional establece el orden de inserción (omítelo para agregar al final); el cuerpo de éxito es JSON.
xmind_reorder_children	Cambia el orden de los hijos de un tema sin cambiar de padre.
xmind_set_topic_properties	Establece o actualiza metadatos de tema (notas, etiquetas, marcadores, enlace, remove_markers); las reglas de borrado están en la herramienta.
xmind_set_topic_properties_bulk	Aplica las mismas actualizaciones de metadatos que xmind_set_topic_properties a muchos IDs de temas en una sola lectura/escritura.
xmind_add_floating_topic	Agrega un tema flotante desprendido no conectado a la jerarquía principal.
xmind_add_relationship	Dibuja un conector etiquetado entre dos temas cualesquiera.
xmind_delete_relationship	Elimina una relación por ID (de xmind_list_relationships).
xmind_add_summary	Agrega una llamada de resumen que abarca un rango de temas hermanos.
xmind_add_boundary	Agrega un recinto visual de límite alrededor de todos los hijos de un tema.

Nivel 4: Utilidades

Herramienta	Descripción
xmind_flatten_to_outline	Exporta una hoja o subárbol como texto plano indentado o Markdown.
xmind_import_from_outline	Construye un mapa o rama desde un esquema de texto plano indentado o Markdown.
xmind_find_and_replace	Renombra temas que coinciden con un patrón en toda una hoja.

---

Desarrollo

Solo la primera vez, instala las herramientas locales del proyecto (golangci-lint, goimports) en ./bin:

make setup

Luego:

# Build (binary in ./bin/xmind-mcp), tests, and lint
make build test lint

# Run the server locally (stdio MCP)
make run

El fixture de prueba principal se encuentra en testdata/kitchen-sink.xmind. Ejercita cada funcionalidad compatible de XMind y debe usarse como referencia base para el desarrollo y las pruebas de cualquier handler. Ese archivo se almacena en Git LFS; usa un clon con LFS habilitado (o ejecuta git lfs pull) antes de make test, o las pruebas fallarán en un stub de puntero.

---

Licencia

MIT. Consulta LICENSE.