freeplane-mcp

MCP-сервер, который позволяет AI-агентам, таким как Claude Desktop, Cursor и opencode, читать и изменять активную карту Freeplane через gRPC-плагин freeplane_plugin_grpc.

В отличие от одноразовых MCP-серверов типа «Markdown → image», изменения применяются в реальном времени к текущей открытой карте Freeplane.

Архитектура

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

Требования

• Python 3.10+

• Freeplane, запущенный с установленным gRPC-плагином

• Порт gRPC Freeplane по умолчанию: 50051

Установка

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

Запуск

stdio

Транспорт по умолчанию для Claude Desktop, Cursor, opencode и др.:

.venv/bin/freeplane-mcp

Streamable HTTP

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

Конфигурация

MCP-инструменты

export_map

Экспортирует текущую карту в канонический JSON.

Поддерживаемые поля включают:

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

import_map

Импортирует интеллект-карту из канонического JSON.

Поддерживаемые значения insert_mode:

• root — вставка под корневой узел карты; по умолчанию

• node — вставка под insert_node_id

• selected — вставка под выбранный узел

Тестирование

Экспортируйте текущую карту:

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

Импортируйте карту и снова экспортируйте её:

.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-клиента

Пример конфигурации stdio:

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

Конфигурация HTTP:

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

Примечания о формате JSON

Канонический JSON-формат определяется файлом JsonHelper.java плагина.

Импорт поддерживает _fp_import_root_node:

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

вставляет ниже корневого узла карты.

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

вставляет ниже указанного узла.

Без обёртки карта вставляется ниже текущего выбранного узла.

Устаревший формат также поддерживается:

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

Лицензия

MIT