Gmail MCP Server

Gmail MCP Server

Un servidor MCP (Model Context Protocol) que proporciona capacidades de integración con Gmail a clientes MCP como Claude Desktop.

Características

• Ver correos electrónicos recientes de tu bandeja de entrada de Gmail
• Buscar correos electrónicos usando la sintaxis de búsqueda de Gmail
• Autenticación segura OAuth2 con la API de Gmail

Configuración

1. Configuración del Proyecto de Google Cloud

1. Crea un proyecto de Google Cloud en https://console.cloud.google.com/
2. Habilita la API de Gmail
3. Crea credenciales OAuth 2.0:
   • Tipo de aplicación: Aplicación de escritorio
   • Descarga las credenciales como credentials.json

2. Instalación

# Create a conda environment
conda create -n mcp-gmail python=3.12
conda activate mcp-gmail

# Install the package
cd gmail-mcp-server
pip install -e .

3. Configuración para Claude Desktop

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/conda/envs/mcp-gmail/bin/python",
      "args": ["-m", "gmail_mcp_server.server"],
      "env": {
        "PYTHONPATH": "/path/to/gmail-mcp-server/src",
        "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json",
        "GMAIL_TOKEN_FILE": "/path/to/token.json"
      }
    }
  }
}

Reemplaza /path/to/ con tus rutas reales. El archivo de token se creará automáticamente cuando te autentiques por primera vez.

4. Primera ejecución

Cuando intentes acceder a Gmail a través de Claude por primera vez, se te pedirá que autorices la aplicación en tu navegador. Después de la autorización, tus credenciales se guardarán en el archivo de token para uso futuro.

Recursos disponibles

• gmail://inbox/recent - Devuelve tus 10 correos electrónicos más recientes

Herramientas disponibles

• search_emails
  • Descripción: Busca correos electrónicos de Gmail con una consulta
  • Parámetros:
    • query (obligatorio): Consulta de búsqueda de Gmail (usa la sintaxis de búsqueda estándar de Gmail)
    • max_results (opcional): Número máximo de resultados a devolver (por defecto: 10)

Ejemplo de búsqueda:

Could you show me any emails from sanrio in the last two days?

Seguridad

Este servidor requiere autenticación OAuth2 con Gmail:

• Se te pedirá que autorices el acceso en tu navegador en el primer uso
• Las credenciales se almacenan localmente en el archivo de token especificado
• El acceso se puede revocar en cualquier momento a través de la configuración de tu cuenta de Google
• Solo se solicita acceso de lectura a Gmail (sin permisos de escritura)

Variables de entorno

• GMAIL_CREDENTIALS_FILE (obligatorio): Ruta a tu archivo de credenciales OAuth de Google
• GMAIL_TOKEN_FILE (obligatorio): Ruta donde se guardará el token de autenticación

Para pruebas, puedes ejecutar el servidor directamente:

GMAIL_CREDENTIALS_FILE="/path/to/credentials.json" \
GMAIL_TOKEN_FILE="/path/to/token.json" \
python -m gmail_mcp_server.server

Desarrollo

El servidor utiliza el Model Context Protocol para proporcionar:

• Acceso a recursos de correos electrónicos recientes
• Soporte de herramientas para búsqueda de correos electrónicos
• Flujo de autenticación OAuth2 seguro
• Actualización automática de tokens

Registro

El servidor registra información detallada sobre sus operaciones en stderr, incluyendo:

• Información de inicio del servidor
• Estado de autenticación
• Uso de recursos y herramientas
• Cualquier error o problema

Contribuciones

¡Las solicitudes de extracción son bienvenidas! Asegúrate de:

• Actualizar la documentación para cualquier característica nueva
• Añadir manejo de errores adecuado
• Probar el flujo OAuth con las nuevas características
• Seguir el estilo de código existente