Skip to main content
Glama
deenesjakoruzh
shyinlim

Mindmup2GoogleDriveMCP

by shyinlim
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

MCP-сервер MindMup2 Google Drive

Сервер протокола контекста модели (MCP), который позволяет ИИ-клиентам (Claude Code, Cursor) искать, читать и углубляться в интеллект-карты MindMup 2 в формате .mup, хранящиеся на Google Drive — без выгрузки 3-мегабайтного дерева JSON в модель. Большие карты автоматически преобразуются в структуру дерева; затем ИИ может переходить к конкретным разделам по node_path.

Совместимость: Claude Code, Cursor (транспорт HTTP). Не поддерживается: Claude Desktop (только stdio).

💫 Результат

ezgif-5b4a0eb3a275f8.gif

Related MCP server: Google-Workspace-MCP-Server

✨ Функции

  • Поиск файлов MindMup по всему вашему Google Drive (только чтение)

  • Навигация по дереву + детализация разделов для больших интеллект-карт — маленькие файлы возвращают полное содержимое, большие — структуру, в которую можно углубиться

  • Изоляция кэша для каждого клиента через заголовок X-Client-Id, чтобы разные пользователи/инструменты не использовали общий кэшированный контент

  • Режим разработки с горячей перезагрузкой через fastmcp run --reload + примонтированный исходный код

  • Сервер FastMCP со встроенными эндпоинтами /health и /ping

  • Docker Compose для разработки и продакшена

🗺️ Сквозной процесс

1. Set up Google Cloud service account     →  download JSON key
2. Share your Drive folder with the SA     →  Viewer access
3. Base64-encode the JSON key              →  for X-Google-Credential header
4. Run the server  (Docker or Python)      →  http://127.0.0.1:9805
5. Configure your MCP client (Claude/Cursor) with the base64 credential
6. Verify  →  curl http://127.0.0.1:9805/health

🔧 Доступные инструменты MCP

Инструмент

Описание

list_files

Список файлов MindMup с Google Drive (папки и файлы не в формате .mup по умолчанию отфильтровываются). Возвращает id, name, folder_url, size, modified_time.

read_mindmap

Чтение файла MindMup по file_id или file_name (один из параметров обязателен; имя использует первое частичное совпадение). Маленькие файлы (<100 КБ ИИ-словаря) возвращают content_type: "full". Большие файлы возвращают content_type: "outline_only" с tree_outline, section_stats и suggested_start_paths.

search_mindmap

Поиск узлов по ключевому слову. Параметры: file_id, keyword, опционально node_path (область поддерева), max_results=30, normalize_whitespace=True. Возвращает узлы с node_path, title_preview, breadcrumb, children_count.

get_mindmap_section

Детализация раздела по node_path (целые числа через точку, корень — 1, например, "1.2.3"). Опционально max_depth, offset=0, limit=0. Возвращает `content_type: "full"

"outline_only"

"paginated"

"truncated"` — автоматически переключается, если раздел все еще слишком велик.

Рекомендуемый рабочий процесс для ИИ-агентов: list_files → read_mindmap → если outline_only, то либо search_mindmap (по ключевому слову), либо get_mindmap_section (по node_path из suggested_start_paths).

🚀 Начало работы

Предварительные требования

  • Python 3.12+

  • Docker и docker-compose (требуются для make run-dev-docker / make run-prod); см. makefile

  • Аккаунт Google Cloud Platform

  • MCP-клиент, поддерживающий транспорт HTTP (Claude Code или Cursor)

Настройка Google Drive API

Шаг

Описание

Изображение

1

Перейдите в Google Cloud Console и создайте новый проект (бесплатного уровня достаточно — для Drive API оплата не требуется).

2

Включите Google Drive API.

3

Создайте учетные данные сервисного аккаунта:- "IAM & Admin" → "Service Accounts" → "Create Service Account"- Роль на уровне проекта не нужна (доступ управляется через общий доступ к диску)- Откройте SA → вкладка "Keys" → "Add Key" → JSON → скачайте файл ключа.

google_service_acc.jpg

4

Закодируйте весь JSON-файл ключа в Base64 (см. Справочник заголовков).⚠️ Добавьте JSON-файл в .gitignore — никогда не коммитьте его.

5

Предоставьте доступ к папке Google Drive для SA:- Скопируйте значение client_email из JSON- Нажмите правой кнопкой мыши на папку → "Поделиться" → вставьте email- Предоставьте доступ Читатель, снимите галочку "Уведомить людей"- Доступ распространяется на подпапки.

google_drive_share_list2.jpg

Примечание о правах доступа: Сервер запрашивает auth/drive + auth/drive.file. Несмотря на широкие права, при предоставлении доступа на уровне папки "Читатель", SA может читать только то, чем вы поделились. Корпоративные аккаунты могут блокировать внешний доступ — если это так, попросите администратора разрешить доступ для сервисных аккаунтов в вашем домене.

Запуск сервера

Docker (рекомендуется):

make run-dev-docker   # dev: hot-reload, source bind-mounted
make run-prod         # prod: no reload

Прямой запуск Python (без Docker):

pip install -r requirements.txt
python3 run.py
# Optionally: MCP_TRANSPORT=streamable-http python3 run.py

Проверка сервера

curl http://127.0.0.1:9805/health
# => {"result":"success","time":"...","message":"MCP server is running. ..."}

Если вы не получили success, проверьте docker logs <container> (в режиме Docker) или stdout (в режиме Python).

Запуск тестов

pip install -r requirements.txt
pytest

Конфигурация MCP-клиента

Добавьте в конфигурацию вашего MCP-клиента (~/.claude/mcp.json для Claude Code или настройки Cursor MCP):

{
    "mcpServers": {
        "mindmup-gdrive": {
            "type": "http",
            "url": "http://127.0.0.1:9805/mcp",
            "headers": {
                "X-Google-Credential": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VuXXXXXXXXXXX",
                "X-Client-Id": "shyin-claude-code"
            }
        }
    }
}

Справочник заголовков

Заголовок

Обязательно

Описание

X-Google-Credential

✅

Ваш JSON сервисного аккаунта, закодированный в base64. Используйте base64encode.org и вставьте результат сюда. ⚠️ Base64 — это кодирование, а не шифрование — конфигурация MCP-клиента хранится на диске в открытом виде, поэтому не синхронизируйте её с публичными репозиториями / незашифрованными облачными бэкапами.

X-Client-Id

Опционально

Уникальный идентификатор для пользователя + инструмента, например shyin-claude-code. Используется как часть ключа кэша (X-Client-Id, credential_hash, file_id) для изоляции кэшированного контента между клиентами. Если пропущено, используется default (кэш может быть общим с другими клиентами) и записывается предупреждение. Рекомендуемый формат: <ваше-имя>-<имя-инструмента>. Используйте значение с высокой энтропией, чтобы избежать коллизий с другими пользователями.

🩺 Устранение неполадок

Симптом

Вероятная причина / решение

health ничего не возвращает / connection refused

Сервер не запущен. Проверьте docker ps или stdout. Порт 9805 уже занят? Отредактируйте mcp_deployment/docker-compose-dev.yml для переназначения.

Google Drive authentication failed

Неверный base64. Проверка: `echo "$CRED"

base64 -d

jq .client_email` — должен вывести email SA.

list_files возвращает пустоту

(a) Папка предоставлена не тому email — должен совпадать с client_email в JSON. (b) Файлы не в формате .mup — вызовите с mindmup_only=False для проверки видимости. (c) Политика организации Workspace блокирует внешний доступ.

Ошибка сборки Docker

Убедитесь, что демон Docker запущен. Перезапустите make run-dev-docker.

Изменения не применяются в режиме разработки

Горячая перезагрузка отслеживает только исходный код Python. Перезапустите контейнер после изменения зависимостей или переменных окружения.

🏗️ Структура проекта

├── mcp_deployment/
│   ├── docker-compose-dev.yml
│   ├── docker-compose-prod.yml
│   └── Dockerfile
├── src/
│   ├── core/
│   │   ├── gdrive_client.py    # Google Drive API client
│   │   ├── gdrive_feature.py   # Google Drive feature implementation
│   │   ├── mcp_server.py       # Main MCP server with read tools
│   │   └── mindmup_parser.py   # MindMup parsing + tree navigation
│   ├── model/
│   │   ├── common_model.py     # Common data models
│   │   ├── gdrive_model.py     # Google Drive data models
│   │   └── mindmup_model.py    # Mind map data models (with to_ai_dict)
│   └── utility/
│       ├── enum.py             # Enumerations and constants
│       └── logger.py           # Logging utilities
├── tests/                      # Unit tests
├── plans/                      # Implementation plans
├── run.py                      # Main entry point
├── requirements.txt            # Python dependencies
└── makefile                    # Build and deployment commands

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Google-Workspace-MCP-Server

    giuseppe-coco
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server that seamlessly interacts with your Google Calendar, Gmail, Drive and so on.
    30
    MIT

  • manus-mcp

    mitjaeichhorn
    F
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that enables interaction with Google Drive through the Google Cloud API. It allows users to list, read, and upload files directly from MCP-compatible clients like manus.im or Cursor.
    -

  • mcp-server-drive

    apercura
    F
    license
    Not graded
    quality
    C
    maintenance
    A read-only Google Drive MCP server that allows searching files, reading file content (with auto-export for Google Docs, Sheets, Slides), and retrieving file metadata via OAuth authentication.
    8 npm
    2
    -