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.

Related MCP server: gmail-drive-mcp-server

Configuración

1. Proyecto de Google Cloud

1. Ve a Google Cloud Console

2. Crea un proyecto nuevo (o utiliza uno existente)

3. Habilita estas API:

   • Gmail API

   • Google Calendar API

   • People API (para contactos)

4. 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

Gmail (9 herramientas)

Calendar (6 herramientas)

Contactos (2 herramientas)

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/:

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:

1. Haz un fork de este repositorio

2. Crea tu propio proyecto de Google Cloud y credenciales de OAuth (ver Configuración arriba)

3. Compila y apunta tu configuración de Claude Code al dist/index.js de tu fork

4. 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