Servidor MCP de Gmail

El servidor MCP de Gmail es un servidor MCP stdio basado en Node.js/TypeScript, diseñado para permitir que OpenClaw lea correos electrónicos de Gmail a través del Protocolo de Contexto de Modelo (MCP).

Funcionalidades

• Utiliza la autorización OAuth 2.0 de la API de Gmail, con un alcance de solo lectura: https://www.googleapis.com/auth/gmail.readonly

• list_emails: lista los correos de la bandeja de entrada, admite maxResults y filtrado mediante la sintaxis de búsqueda de Gmail query

• get_email: lee los detalles de un correo electrónico específico mediante su messageId

• search_emails: busca correos electrónicos utilizando la sintaxis de búsqueda de Gmail

• list_labels: lista todas las etiquetas/carpetas de Gmail

• Admite el transporte stdio de MCP, permitiendo su invocación por parte de OpenClaw

Requisitos del entorno

• Node.js 18 o superior

• npm

• Una cuenta de Google con acceso a la API de Gmail

Instalación

npm install
npm run build

Crear credenciales OAuth en Google Cloud Console

1. Abre Google Cloud Console.

2. Crea o selecciona un proyecto.

3. Ve a APIs & Services -> Library, busca y habilita la Gmail API.

4. Ve a APIs & Services -> OAuth consent screen.

5. Selecciona el tipo de usuario. Para uso personal, generalmente se elige External.

6. Completa el nombre de la aplicación, el correo electrónico de soporte al usuario y el correo electrónico de contacto del desarrollador.

7. En el paso de Scopes (ámbitos), añade el permiso de solo lectura de Gmail: https://www.googleapis.com/auth/gmail.readonly.

8. Si la aplicación está en estado de Testing, añade tu cuenta de Gmail en Test users.

9. Ve a APIs & Services -> Credentials.

10. Haz clic en Create Credentials -> OAuth client ID.

11. En Application type, selecciona Desktop app.

12. Descarga el archivo JSON después de crearlo.

Colocar credentials.json

Crea el directorio de configuración y guarda el JSON de OAuth descargado como:

mkdir -p ~/.gmail-mcp
chmod 700 ~/.gmail-mcp
cp /path/to/downloaded/client_secret.json ~/.gmail-mcp/credentials.json
chmod 600 ~/.gmail-mcp/credentials.json

La ruta final debe ser:

~/.gmail-mcp/credentials.json

Ejecutar el flujo de autorización

npm run auth

El script realizará lo siguiente:

• Iniciará un servicio de callback OAuth local temporal

• Abrirá el navegador para realizar la autorización de Google

• Guardará el token en ~/.gmail-mcp/token.json una vez completada la autorización

Si el navegador no se abre automáticamente, la terminal imprimirá la URL de autorización; simplemente cópiala y pégala en tu navegador.

Iniciar el servidor MCP

npm run start

start utiliza el transporte stdio, generalmente iniciado por OpenClaw como un subproceso del servidor MCP, por lo que no es necesario ejecutarlo manualmente de forma prolongada.

Ejemplo de configuración de OpenClaw MCP

Apunta el comando al punto de entrada compilado del proyecto:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/Volumes/DevDisk/symbol/gmailMCP/dist/src/index.js"]
    }
  }
}

También puedes iniciarlo con npm dentro del directorio del proyecto:

{
  "mcpServers": {
    "gmail": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "/Volumes/DevDisk/symbol/gmailMCP"
    }
  }
}

Descripción de los parámetros de las herramientas

list_emails

Lista los correos electrónicos de la bandeja de entrada.

{
  "maxResults": 10,
  "query": "from:example@gmail.com newer_than:7d"
}

• maxResults: opcional, predeterminado 10, máximo 50

• query: opcional, sintaxis de búsqueda de Gmail, limitará la consulta a la bandeja de entrada (INBOX)

get_email

Lee los detalles de un correo electrónico específico.

{
  "messageId": "18f..."
}

Los campos devueltos incluyen remitente, destinatario, asunto, fecha, etiquetas, cuerpo de texto, cuerpo HTML y metadatos de archivos adjuntos.

search_emails

Busca correos electrónicos en Gmail.

{
  "query": "subject:invoice has:attachment newer_than:30d",
  "maxResults": 10
}

• query: obligatorio, admite la sintaxis de búsqueda de Gmail

• maxResults: opcional, predeterminado 10, máximo 50

list_labels

Lista todas las etiquetas/carpetas.

{}

Ubicación de archivos

• Credenciales OAuth: ~/.gmail-mcp/credentials.json

• Token OAuth: ~/.gmail-mcp/token.json

• Punto de entrada del servidor MCP: dist/src/index.js

Preguntas frecuentes

Missing Gmail OAuth credentials

Confirma que has descargado el JSON del cliente OAuth de Google y lo has guardado en:

~/.gmail-mcp/credentials.json

Missing Gmail OAuth token

Ejecuta primero:

npm run auth

access_denied o aplicación no verificada

Si la pantalla de consentimiento de OAuth sigue en estado Testing, debes añadir tu cuenta de Gmail actual a los Test users.

invalid_grant

Elimina el token antiguo y vuelve a autorizar:

rm ~/.gmail-mcp/token.json
npm run auth