MindmupGoogleDriveMcp

Servidor MCP de MindMup2 Google Drive

Un servidor de Model Context Protocol (MCP) que permite a los clientes de IA (Claude Code, Cursor) buscar, leer y profundizar en mapas mentales de MindMup 2 .mup almacenados en Google Drive — sin volcar un árbol JSON de 3MB en el modelo. Los mapas grandes se resumen automáticamente en un esquema de árbol; la IA luego profundiza en secciones específicas mediante node_path.

Compatibilidad: Claude Code, Cursor (transporte HTTP). No compatible: Claude Desktop (solo stdio).

💫 Resultado

✨ Características

• Buscar archivos MindMup en todo tu Google Drive (solo lectura)
• Navegación por árbol + profundización en secciones para mapas mentales grandes — los archivos pequeños devuelven el contenido completo, los archivos grandes devuelven un esquema en el que puedes profundizar
• Aislamiento de caché por cliente mediante el encabezado X-Client-Id, para que diferentes usuarios/herramientas no compartan contenido en caché
• Modo de desarrollo con recarga en caliente mediante fastmcp run --reload + fuente montada por bind
• Servidor FastMCP con endpoints integrados /health y /ping
• Docker Compose para desarrollo y producción

🗺️ Flujo de extremo a extremo

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

🔧 Herramientas MCP disponibles

Flujo de trabajo sugerido para agentes de IA: list_files → read_mindmap → si outline_only, ya sea search_mindmap (por palabra clave) o get_mindmap_section (por node_path de suggested_start_paths).

🚀 Primeros pasos

Requisitos previos

• Python 3.12+
• Docker y docker-compose (requeridos para make run-dev-docker / make run-prod); Ref. makefile
• Cuenta de Google Cloud Platform
• Un cliente MCP que admita transporte HTTP (Claude Code o Cursor)

Configuración de la API de Google Drive

Paso	Descripción	Imagen
1	Ve a Google Cloud Console y crea un nuevo proyecto (el nivel gratuito es suficiente — no se requiere facturación para la API de Drive).
2	Habilita la API de Google Drive.
3	Crea credenciales de cuenta de servicio: - "IAM y Administración" → "Cuentas de servicio" → "Crear cuenta de servicio" - No se necesita rol a nivel de proyecto (el uso compartido de Drive maneja la autenticación) - Abre la SA → pestaña "Claves" → "Agregar clave" → JSON → descarga el archivo de clave.
4	Codifica en base64 todo el archivo de clave JSON (consulta Referencia de encabezados). ⚠️ Agrega el archivo JSON a .gitignore — nunca lo subas al repositorio.
5	Comparte tu carpeta de Google Drive con la SA: - Copia el valor de client_email del JSON - Haz clic derecho en la carpeta → Compartir → pega el correo - Otorga acceso de Lector, desmarca "Notificar a las personas" - El uso compartido se propaga a las subcarpetas.

Nota sobre los alcances: El servidor solicita auth/drive + auth/drive.file. A pesar del alcance amplio, con el uso compartido a nivel de carpeta Viewer, la SA solo puede leer lo que has compartido. Las cuentas administradas por Workspace pueden bloquear el uso compartido externo — si es así, pide a tu administrador que permita el uso compartido de cuentas de servicio para tu dominio.

Ejecutar el servidor

Docker (recomendado):

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

Python directo (sin Docker):

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

Verificar el servidor

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

Si no obtienes success, revisa docker logs <container> (modo Docker) o stdout (modo Python).

Ejecutar pruebas

pip install -r requirements.txt
pytest

Configuración del cliente MCP

Agrega a la configuración de tu cliente MCP (~/.claude/mcp.json para Claude Code, o la configuración MCP de Cursor):

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

Referencia de encabezados

🩺 Solución de problemas

🏗️ Estructura del proyecto

├── 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