mariana-google-mcp

Un servidor MCP (Model Context Protocol) personalizado que brinda a Claude Code acceso a Gmail, Google Calendar y Google Contacts, con valores predeterminados centrados en la seguridad.

Filosofía de diseño

Este servidor está diseñado para un operador que desea que la IA ayude a gestionar su espacio de trabajo de Google sin riesgo de daños accidentales:

No envía correos electrónicos. Puedes redactar borradores, pero el envío requiere una acción manual en Gmail.
No elimina nada. Gmail utiliza una etiqueta "To Be Deleted" (eliminación lógica). Calendar antepone "DELETE - " a los títulos de los eventos. Tú revisas y confirmas en la interfaz de Google.
Cada cambio queda registrado. Un registro de acciones en formato JSONL de solo adición registra cada operación de escritura con marcas de tiempo, nombre de la herramienta, cuenta y resumen.
Soporte para múltiples cuentas. Gestiona cuentas personales y de trabajo con alias personalizados.

Configuración

1. Proyecto de Google Cloud

Ve a Google Cloud Console
Crea un proyecto nuevo (o utiliza uno existente)
Habilita estas API:
- Gmail API
- Google Calendar API
- People API (para contactos)
Crea credenciales de OAuth 2.0:
- Tipo de aplicación: Aplicación de escritorio
- Descarga el ID de cliente y el secreto de cliente

2. Instalación y compilación

git clone https://github.com/marianasmall/mariana-google-mcp.git
cd mariana-google-mcp
npm install
npm run build

3. Añadir a Claude Code

Añade esto a tu ~/.claude.json bajo mcpServers:

{
  "mcpServers": {
    "mariana-google-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mariana-google-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Reemplaza /path/to/ con la ruta real a tu clon y completa tus credenciales de OAuth.

4. Autenticación

Después de reiniciar Claude Code, ejecuta la herramienta google_auth. Se abrirá una ventana del navegador para el consentimiento de OAuth. Una vez autorizado, tu token se almacenará localmente y se actualizará automáticamente.

Herramientas disponibles (19)

Autenticación y estado

Herramienta	Descripción
`google_auth`	Autentica una cuenta de Google mediante el flujo de navegador OAuth
`google_status`	Comprueba el estado de conexión de todas las cuentas configuradas

Gmail (9 herramientas)

Herramienta	Descripción
`gmail_search`	Busca mensajes usando la sintaxis de consulta de Gmail
`gmail_read`	Lee un mensaje específico por ID (contenido completo)
`gmail_list_labels`	Lista todas las etiquetas/carpetas de Gmail
`gmail_draft`	Crea un borrador de correo electrónico (NO lo envía)
`gmail_create_label`	Crea una nueva etiqueta (admite anidamiento con `/`)
`gmail_apply_label`	Aplica una etiqueta a uno o más mensajes
`gmail_remove_label`	Elimina una etiqueta de uno o más mensajes
`gmail_create_filter`	Crea una regla de filtro (criterios de coincidencia → acciones)
`gmail_move_to_delete`	Eliminación lógica: mueve mensajes a una etiqueta "To Be Deleted"

Calendar (6 herramientas)

Herramienta	Descripción
`calendar_list`	Lista los próximos eventos del calendario
`calendar_search`	Busca eventos por palabra clave
`calendar_get`	Obtiene los detalles completos de un evento específico
`calendar_create`	Crea un evento (NO envía invitaciones por defecto)
`calendar_update`	Modifica un evento existente (NO notifica a los asistentes por defecto)
`calendar_flag_delete`	Eliminación lógica: antepone "DELETE - " al título del evento
`calendar_availability`	Comprueba el estado de disponibilidad para un rango de fechas

Contactos (2 herramientas)

Herramienta	Descripción
`contacts_search`	Busca contactos por nombre, correo electrónico o teléfono
`contacts_list`	Lista los contactos, opcionalmente filtrados por grupo

Soporte para múltiples cuentas

Puedes autenticar varias cuentas de Google con nombres amigables:

google_auth account_name: "primary"
google_auth account_name: "newsletters"
google_auth account_name: "work"

La mayoría de las herramientas aceptan un parámetro opcional account. Si se omite, utilizan la cuenta predeterminada. Usa google_status para ver todas las cuentas configuradas y su estado.

Archivos de configuración

Toda la configuración se almacena en ~/.config/mariana-google-mcp/:

Archivo	Propósito
`config.json`	Registro de cuentas (nombres, hashes de correo, valores predeterminados)
`tokens/<hash>.json`	Tokens de OAuth por cuenta (actualizados automáticamente)
`actions.jsonl`	Registro de solo adición de todas las mutaciones

Los tokens se almacenan mediante el hash del correo electrónico, no el correo en texto plano, para una capa de indirección.

Registro de acciones

Cada operación de escritura (borradores, creación/actualización de calendario, eliminaciones lógicas) se registra en ~/.config/mariana-google-mcp/actions.jsonl en este formato:

{"timestamp":"2026-04-03T10:30:00.000Z","tool":"gmail_draft","account":"primary","summary":"Draft created: subject='Meeting follow-up'"}

El registro es de solo adición y nunca es modificado por el servidor. Revísalo en cualquier momento para auditar lo que ha hecho Claude.

Bifurcación y uso

Para usar esto con tu propia cuenta de Google:

Haz un fork de este repositorio
Crea tu propio proyecto de Google Cloud y credenciales de OAuth (ver Configuración arriba)
Compila y apunta tu configuración de Claude Code al dist/index.js de tu fork
Ejecuta google_auth para autenticarte

No se necesitan cambios en el código: todos los datos específicos de la cuenta residen en archivos de configuración y variables de entorno.

Stack tecnológico

TypeScript
@modelcontextprotocol/sdk — Implementación del protocolo MCP
googleapis — Cliente de la API de Google
google-auth-library — Gestión de tokens OAuth2
zod — Validación de entrada

Licencia

MIT

Mariana Google MCP