freeplane-mcp

Ein MCP-Server, der KI-Agenten wie Claude Desktop, Cursor und opencode das Lesen und Ändern einer laufenden Freeplane-Mindmap über das freeplane_plugin_grpc gRPC-Plugin ermöglicht.

Im Gegensatz zu einmaligen „Markdown → Bild“-MCP-Servern werden Änderungen live auf die aktuell geöffnete Freeplane-Mindmap angewendet.

Architecture

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

Requirements

• Python 3.10+

• Freeplane mit installiertem und laufendem gRPC-Plugin

• Standard-freeplane-gRPC-Port: 50051 – (standard Freeplane gRPC port, im Kontext: Freeplane mit installiertem und laufendem gRPC-Plugin).

Installation

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

Ausführen

stdio

Standardtransport für Claude Desktop, Cursor, opencode usw.:9;

.venv/bin/freeplane-mcp

Streamable HTTP

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

Konfiguration

MCP-Werkzeuge

export_map

Exportiert die aktuelle Mindmap als kanonisches JSON.

Die unterstützten Felder umfassen:

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

import_map

Importiert eine Mindmap aus kanonischem JSON.

Unterstützte insert_mode-Werte:

• root — fügt unterhalb des Wurzelknotens der Mindmap ein; Standard? Punkt

• node — fügt unterhalb von insert_node_id ein

• selected — fügt unterhalb des aktuell ausgewählten Knotens ein

Test

Aktuelle Mindmap exportieren:

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

Eine Mindmap importieren und erneut exportieren:

.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())
"

MCP-Client-Konfiguration

Beispielkonfiguration für stdio:

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

HTTP-Konfiguration:

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

Hinweise zum JSON-Format

Das kanonische JSON-Format wird durch JsonHelper.java des Plugins definiert.

Der Import unterstützt _fp_import_root_node:

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

fügt unterhalb des Wurzelknotens der Mindmap ein.

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

fügt unterhalb eines bestimmten Knotens ein.

Ohne den Wrapper wird die Mindmap unterhalb des aktuell ausgewählten Knotens eingefügt.

Auch das Legacy-Format wird unterstützt:

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

Lizenz

MIT