Skip to main content
Glama
deenesjakoruzh
shyinlim

Mindmup2GoogleDriveMCP

by shyinlim
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

Servidor MCP de MindMup a Google Drive

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

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

💫 Resultado

ezgif-5b4a0eb3a275f8.gif

Related MCP server: Google-Workspace-MCP-Server

✨ Características

  • Buscar archivos de MindMup en todo su Google Drive (solo lectura)

  • Navegación por árbol + exploración de secciones para mapas mentales grandes: los archivos pequeños devuelven el contenido completo, los archivos grandes devuelven un esquema que puede explorar

  • 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 + código fuente montado

  • Servidor FastMCP con puntos finales /health y /ping integrados

  • 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

Herramienta

Descripción

list_files

Lista los archivos de MindMup de Google Drive (las carpetas y los archivos que no son .mup se filtran de forma predeterminada). Devuelve id, name, folder_url, size, modified_time.

read_mindmap

Lee un archivo de MindMup por file_id o file_name (se requiere uno; el nombre utiliza la primera coincidencia parcial). Los archivos pequeños (<100 KB de dictado de IA) devuelven content_type: "full". Los archivos grandes devuelven content_type: "outline_only" con tree_outline, section_stats y suggested_start_paths.

search_mindmap

Busca nodos por palabra clave. Parámetros: file_id, keyword, node_path opcional (ámbito de subárbol), max_results=30, normalize_whitespace=True. Devuelve nodos con node_path, title_preview, breadcrumb, children_count.

get_mindmap_section

Explora una sección por node_path (enteros separados por puntos, la raíz es 1, p. ej., "1.2.3"). max_depth opcional, offset=0, limit=0. Devuelve `content_type: "full"

"outline_only"

"paginated"

"truncated"`: cambia automáticamente cuando la sección sigue siendo demasiado grande.

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

🚀 Introducción

Requisitos previos

  • Python 3.12+

  • Docker y docker-compose (necesarios 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

Vaya a Google Cloud Console y cree un nuevo proyecto (el nivel gratuito está bien; no se requiere facturación para la API de Drive).

2

Habilite la API de Google Drive.

3

Cree 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 gestiona la autenticación)- Abra la SA → pestaña "Claves" → "Agregar clave" → JSON → descargue el archivo de clave.

google_service_acc.jpg

4

Codifique en Base64 todo el archivo de clave JSON (consulte Referencia de encabezado).⚠️ Agregue el archivo JSON a .gitignore: nunca lo confirme.

5

Comparta su carpeta de Google Drive con la SA:- Copie el valor client_email del JSON- Haga clic derecho en la carpeta → Compartir → pegue el correo electrónico- Otorgue acceso de Lector, desmarque "Notificar a las personas"- El uso compartido se propaga a las subcarpetas.

google_drive_share_list2.jpg

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 de Lector, la SA solo puede leer lo que usted ha compartido. Las cuentas administradas por Workspace pueden bloquear el uso compartido externo; si es así, pídale a su administrador que permita el uso compartido de cuentas de servicio para su 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 obtiene success, verifique docker logs <container> (modo Docker) o stdout (modo Python).

Ejecutar pruebas

pip install -r requirements.txt
pytest

Configuración del cliente MCP

Agréguelo a la configuración de su cliente MCP (~/.claude/mcp.json para Claude Code, o su configuración de 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 encabezado

Encabezado

Requerido

Descripción

X-Google-Credential

✅

Su JSON de cuenta de servicio, codificado en base64. Use base64encode.org y pegue el resultado aquí. ⚠️ Base64 es codificación, no cifrado: la configuración del cliente MCP se encuentra en texto plano en el disco, así que no la sincronice con repositorios públicos / copias de seguridad en la nube sin cifrar.

X-Client-Id

Opcional

Un identificador único por usuario + herramienta, p. ej., shyin-claude-code. Se utiliza como parte de la clave de caché (X-Client-Id, credential_hash, file_id) para aislar el contenido almacenado en caché entre clientes. Si se omite, vuelve a default (la caché puede compartirse con otros clientes no configurados) y se registra una advertencia. Formato recomendado: <su-nombre>-<nombre-de-la-herramienta>. Use un valor de alta entropía para evitar colisiones con otros usuarios.

🩺 Solución de problemas

Síntoma

Causa probable / solución

health no devuelve nada / conexión rechazada

El servidor no se está ejecutando. Verifique docker ps o stdout. ¿El puerto 9805 ya está en uso? Edite mcp_deployment/docker-compose-dev.yml para reasignar.

Google Drive authentication failed

Base64 no válido. Verificación de integridad: `echo "$CRED"

base64 -d

jq .client_email` — debería imprimir el correo electrónico de la SA.

list_files devuelve vacío

(a) Carpeta compartida con el correo electrónico incorrecto: debe coincidir con client_email en el JSON. (b) Los archivos no son .mup: llame con mindmup_only=False para confirmar la visibilidad. (c) La política de la organización de Workspace bloquea el uso compartido externo.

La compilación de Docker falla

Asegúrese de que el demonio de Docker se esté ejecutando. Vuelva a ejecutar make run-dev-docker.

Los cambios no se reflejan en el desarrollo

La recarga en caliente solo observa el código fuente de Python. Reinicie el contenedor después de cambios en las dependencias o el entorno.

🏗️ 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

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
    -