freeplane-mcp

Un servidor MCP que permite a agentes de IA como Claude Desktop, Cursor y opencode leer y modificar un mapa mental de Freeplane en ejecución a través del plugin gRPC Claude_plugin_grpc.

A diferencia de los servidores MCP de una sola pasada «Markdown → imagen», los cambios se aplican en tiempo real al mapa de Freeplane que esté abierto actualmente.

Arquitectura

MCP client (Claude / Cursor / opencode)
        │
        │ stdio or Streamable HTTP (MCP SDK)
        ▼
freeplane-mcp (Python, FastMCP)
        │
        │ gRPC (grpcio)
        ▼
Freeplane + org.freeplane.plugin.grpc
(port 50051)

Related MCP server: xmind-mcp

Requisitos

• Python 3.10+

• Freeplane ejecutándose con el plugin gRPC instalado

• Puerto gRPC predeterminado: 50051

Instalación

cd ~/spaces/freeplane-mcp
python -m venv .venv
.venv/bin/pip install -e .

Ejecución

stdio

Transporte predeterminado para Claude Desktop, Cursor, opencode, etc.:

.venv/bin/freeplane-mcp

Streamable HTTP

.venv/bin/freeplane-mcp --transport http --port 8000

Configuración

Herramientas MCP

export_map

Exporta el mapa is actual a JSON canónico.

Los campos admitidos incluyen:

text, id, children, node, note, detail, link, tags, icons, attributes, background_color, folded y relationships.

import_map

Importa un mapa mental from JSON canónico.

Valores admitidos de insert_mode:

• root — inserta debajo de la raíz del mapa; predeterminado

• node — inserta debajo de insert_node_id

• selected — inserta debajo del nodo seleccionado actualmente

Pruebas

Exporta el mapa actual:

.venv/bin/python -c "
import sys; sys.path.insert(0, '.')
from freeplane_mcp.freeplane_grpc import FreeplaneGrpcClient
c = FreeplaneGrpcClient()
print(c.export_map())
"

Importa un mapa y expórtalo de nuevo:

.venv/bin/python -c "
import sys; sys.path.insert(0, '.')
from freeplane_mcp.freeplane_grpc import FreeplaneGrpcClient
c = FreeplaneGrpcClient()
c.import_map('{\"text\": \"Hello from MCP\", \"children\": [{\"text\": \"child 1\"}]}')
print(c.export_map())
"

Configuración del cliente MCP

Ejemplo de configuración con stdio:

{
  "mcpServers": {
    "freeplane": {
      "command": "/home/bebebeka/spaces/freeplane-mcp/.venv/bin/freeplane-mcp"
    }
  }
}

Configuración HTTP:

{
  "mcpServers": {
    "freeplane": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Notas sobre el formato JSON

El formato JSON canónico está definido por el JsonHelper.java del plugin.

La importación admite _fp_import_root_node:

{"_fp_import_root_node": "root", "mindmap": {...}}

inserta debajo de la raíz del mapa.

{"_fp_import_root_node": "ID_...", "mindmap": {...}}

inserta debajo de un nodo específico.

Sin el contenedor, el mapa se inserta debajo del nodo seleccionado actualmente.

El formato heredado también se admite:

{"node text": {"child node": "note"}}

Licencia

MIT