使用说明

📁 MCP Google Drive Server

Servidor MCP (Model Context Protocol) para interactuar con Google Drive

� Tabla de Contenidos

Descripción
Características
Requisitos Previos
Instalación
Configuración
Uso
Herramientas Disponibles
Integración con IDEs
Arquitectura
Solución de Problemas

🎯 Descripción

Este servidor MCP proporciona una interfaz para interactuar con Google Drive a través del Model Context Protocol. Permite a las aplicaciones de IA leer y actualizar archivos de Google Drive de manera sencilla y eficiente.

¿Qué es MCP?

Model Context Protocol (MCP) es un protocolo estándar que permite a las aplicaciones de IA interactuar con fuentes de datos externas de manera estructurada y segura.

✨ Características

🔍 Lectura inteligente de archivos: Soporta Google Docs (Markdown), Sheets (CSV), Slides y archivos de texto
📝 Actualización de contenido: Modifica archivos de Google Drive directamente
🔗 URLs amigables: Acepta URLs completas de Google Drive (no necesitas extraer el ID manualmente)
🐳 Docker-ready: Despliega fácilmente con Docker y Docker Compose
🔄 Auto-detección de tipos: Detecta automáticamente el tipo de archivo y usa el método apropiado
📋 Formato estructurado: Google Docs exportados en Markdown para preservar formato
🛡️ Manejo de errores robusto: Mensajes de error claros y descriptivos

📋 Requisitos Previos

Python 3.14+
uv (gestor de paquetes Python)
Cuenta de Google Cloud con API de Drive habilitada
Docker (opcional, para deployment)

🚀 Instalación

Opción 1: Instalación Local

Clona el repositorio
```
git clone <repository-url>
cd mcp-py
```
Instala las dependencias
```
uv sync
```
Configura las credenciales (ver sección Configuración)

Opción 2: Usando Docker

Clona el repositorio
```
git clone <repository-url>
cd mcp-py
```
Configura las credenciales (ver sección Configuración)
Levanta el contenedor
```
docker-compose up --build -d
```

🔧 Configuración

1. Obtener Credenciales de Google Cloud

Ve a Google Cloud Console
Crea un nuevo proyecto o selecciona uno existente
Habilita la Google Drive API
Ve a Credenciales > Crear credenciales > Cuenta de servicio
Descarga el archivo JSON de credenciales
Guarda el archivo como credentials.json en la raíz del proyecto

2. Configurar Permisos de Archivos

Para que el servidor pueda acceder a tus archivos de Google Drive:

Abre el archivo credentials.json
Copia el valor del campo client_email (ej: my-service@project.iam.gserviceaccount.com)
En Google Drive:
- Haz clic derecho en el archivo que deseas compartir
- Selecciona Compartir
- Pega el email de la cuenta de servicio
- Dale permisos de Editor
- Haz clic en Enviar

⚠️ Importante: Sin compartir el archivo con la cuenta de servicio, obtendrás errores de "Permiso denegado".

3. Variables de Entorno

El servidor detecta automáticamente el entorno:

Desarrollo (local): Lee credentials.json de la raíz del proyecto
Producción (Docker): Lee credenciales desde /run/secrets/google_creds

Para forzar modo producción:

export APP_ENV=production

🎮 Uso

Ejecutar Localmente

uv run mcp dev mcp_server/main.py:mcp

Esto iniciará el servidor MCP en modo desarrollo con inspector en http://localhost:6274

Ejecutar con Docker

# Iniciar el servidor
docker-compose up --build -d

# Ver logs
docker-compose logs -f

# Detener el servidor
docker-compose down

Herramientas Disponibles

1. `get_drive_file_tool`

Obtiene el contenido de un archivo de Google Drive.

Parámetros:

Parámetro	Tipo	Descripción
`url`	`string`	URL completa de Google Drive o file_id

Tipos de archivos soportados:

✅ Google Docs → Exportado como Markdown (preserva estructura: títulos, listas, negritas, cursivas)
✅ Google Sheets → Exportado como CSV (datos tabulares)
✅ Google Slides → Exportado como texto plano
✅ Archivos de texto → .txt, .md, .json, etc.
✅ Otros archivos binarios → Con contenido de texto

💡 Nota sobre Markdown: Google Docs se exporta en formato Markdown, lo que preserva la estructura del documento (encabezados, listas, formato) y facilita la lectura y modificación programática del contenido.

Ejemplos de uso:

# Con URL completa de Google Docs
url = "https://docs.google.com/document/d/1h9sRNgBe.../edit?usp=sharing"
content = await get_drive_file_tool(url)

# Con URL de Google Sheets
url = "https://docs.google.com/spreadsheets/d/1h9sRNgBe.../edit"
csv_content = await get_drive_file_tool(url)

# Con file_id directo
file_id = "1h9sRNgBeEpC3aa3aXqjVaWTUrbjqKAWtvcoIBXdVdss"
content = await get_drive_file_tool(file_id)

Ejemplo de respuesta (Google Docs en Markdown):

# Mi Documento

## Introducción

Este es un párrafo con **texto en negrita** y *texto en cursiva*.

## Sección Principal

- Item de lista 1
- Item de lista 2
  - Sub-item
  
### Subsección

1. Elemento numerado 1
2. Elemento numerado 2

> Esto es una cita o nota importante

Ejemplo de respuesta (Google Sheets en CSV):

Nombre,Edad,Ciudad
Juan,30,Madrid
María,25,Barcelona
Pedro,35,Valencia

2. `update_drive_file_tool`

Actualiza el contenido de un archivo en Google Drive.

Parámetros:

Parámetro	Tipo	Descripción
`file_id`	`string`	ID del archivo a actualizar
`content`	`string`	Nuevo contenido del archivo

Ejemplo de uso:

file_id = "1h9sRNgBeEpC3aa3aXqjVaWTUrbjqKAWtvcoIBXdVdss"
new_content = "Este es el nuevo contenido del archivo"

result = await update_drive_file_tool(file_id, new_content)

Respuesta:

{
  "status": "success",
  "file_name": "Mi Documento.txt"
}

3. `test_server_tool`

Verifica que el servidor está funcionando correctamente.

Parámetros: Ninguno

Ejemplo de uso:

response = await test_server_tool()

Respuesta:

"Test de mcp py exitosa"

🔌 Integración con IDEs

⚠️ Importante: Todas las configuraciones a continuación usan Docker. Asegúrate de que el contenedor esté corriendo:
docker-compose up -d

Warp Terminal

Agrega esta configuración a tu archivo de configuración MCP:

{
  "mcp-py-drive-server": {
    "command": "docker",
    "args": [
      "exec",
      "-i",
      "mcp-py",
      "uv",
      "run",
      "mcp",
      "run",
      "mcp_server/main.py:mcp"
    ],
    "env": {},
    "working_directory": null
  }
}

VS Code

Agrega a tu settings.json:

{
  "mcp.servers": {
    "google-drive": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "mcp-py",
        "uv",
        "run",
        "mcp",
        "run",
        "mcp_server/main.py:mcp"
      ],
      "env": {}
    }
  }
}

Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "google-drive": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "mcp-py",
        "uv",
        "run",
        "mcp",
        "run",
        "mcp_server/main.py:mcp"
      ]
    }
  }
}

Cursor

Agrega a tu configuración de MCP en Cursor:

{
  "mcp.servers": {
    "google-drive": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "mcp-py",
        "uv",
        "run",
        "mcp",
        "run",
        "mcp_server/main.py:mcp"
      ]
    }
  }
}

Windsurf

Configura el servidor MCP en Windsurf:

{
  "mcp.servers": {
    "google-drive": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "mcp-py",
        "uv",
        "run",
        "mcp",
        "run",
        "mcp_server/main.py:mcp"
      ]
    }
  }
}

Configuración Alternativa (Sin Docker)

Si prefieres ejecutar el servidor localmente sin Docker:

{
  "command": "uv",
  "args": ["run", "mcp", "run", "mcp_server/main.py:mcp"],
  "cwd": "/ruta/absoluta/a/mcp-py"
}

💡 Tip: La configuración con Docker es recomendada para ambientes de producción y asegura consistencia entre diferentes máquinas.

🏗️ Arquitectura

Este proyecto sigue una arquitectura en capas clara y modular:

mcp-py/
├── mcp_server/            # Servidor MCP
│   ├── main.py           # Punto de entrada del servidor MCP
│   ├── gateway/          # Integraciones con servicios externos
│   │   └── google_drive_client.py
│   ├── services/         # Lógica de negocio
│   │   └── drive_service.py
│   └── tools/            # Herramientas MCP
│       ├── get_drive_file.py
│       ├── update_drive_file.py
│       └── test_server.py
├── credentials.json       # Credenciales de Google Cloud
├── pyproject.toml        # Dependencias del proyecto
└── docker-compose.yml    # Configuración de Docker

Flujo de datos:

Cliente MCP → Docker → mcp_server/main.py → tools/ → services/ → gateway/ → Google Drive API

Para más detalles sobre la arquitectura, consulta ARCHITECTURE.md.

🐛 Solución de Problemas

Error: "Servicio de Drive no inicializado"

Causa: El archivo credentials.json no se encuentra o tiene errores.

Solución:

Verifica que credentials.json existe en la raíz del proyecto
Verifica que el JSON es válido
Verifica que las credenciales no han expirado

Error: "Permiso denegado" (403)

Causa: El archivo no está compartido con la cuenta de servicio.

Solución:

Abre credentials.json y copia el client_email
Comparte el archivo de Google Drive con ese email
Dale permisos de Editor

El servidor no responde

Solución:

Verifica que el servidor está corriendo: docker ps o revisa logs
Verifica que el puerto no esté en uso
Reinicia el servidor: docker-compose restart

Error al extraer file_id de la URL

Causa: El formato de la URL no es reconocido.

Solución: El servidor acepta estos formatos:

https://docs.google.com/document/d/FILE_ID/edit
https://drive.google.com/file/d/FILE_ID/view
FILE_ID (directo)

Si tu URL es diferente, usa el file_id directamente.

📚 Recursos Adicionales

📄 Licencia

Este proyecto está bajo la licencia MIT. Ver el archivo LICENSE para más detalles.

🤝 Contribuciones

Las contribuciones son bienvenidas! Por favor:

Fork el proyecto
Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
Commit tus cambios (git commit -m 'Add some AmazingFeature')
Push a la rama (git push origin feature/AmazingFeature)
Abre un Pull Request

📧 Soporte

Si encuentras algún problema o tienes preguntas:

Revisa la sección Solución de Problemas
Busca en los Issues existentes
Crea un nuevo Issue si es necesario

Hecho con ❤️ usando MCP

使用说明

📁 MCP Google Drive Server

� Tabla de Contenidos

🎯 Descripción

¿Qué es MCP?

✨ Características

📋 Requisitos Previos

🚀 Instalación

Opción 1: Instalación Local

Opción 2: Usando Docker

🔧 Configuración

1. Obtener Credenciales de Google Cloud

2. Configurar Permisos de Archivos

3. Variables de Entorno

🎮 Uso

Ejecutar Localmente

Ejecutar con Docker

Herramientas Disponibles

1. get_drive_file_tool

2. update_drive_file_tool

3. test_server_tool

🔌 Integración con IDEs

Warp Terminal

VS Code

Claude Desktop

Cursor

Windsurf

Configuración Alternativa (Sin Docker)

🏗️ Arquitectura

🐛 Solución de Problemas

Error: "Servicio de Drive no inicializado"

Error: "Permiso denegado" (403)

El servidor no responde

Error al extraer file_id de la URL

📚 Recursos Adicionales

📄 Licencia

🤝 Contribuciones

📧 Soporte

相关 MCP

文件与终端管理MCP服务

Shell与编码MCP服务器

容器沙箱 MCP 服务器

LLM项目上下文工具

Obsidian MCP 服务器

FTP/FTPS/SFTP 文件管理 MCP 服务器

1. `get_drive_file_tool`

2. `update_drive_file_tool`

3. `test_server_tool`