gmail-multi-mcp-server

Un servidor MCP que conecta Claude con varias cuentas de Gmail a la vez, y expone el mismo conjunto de herramientas que el conector de Gmail integrado. Cada herramiento acepta un argumento adicional account que indica sobre qué buzón actuar: esa es la única diferencia estructural con el conector de un solo buzón.

"Check my work inbox for anything from the lender, and draft the reply from my personal account."

Por qué existe esto

El conector de Gmail integrado autoriza un solo buzón. Si utiliza cuentas separadas —trabajo, personal, un alias de empresa—, tiene que estar cambiando constantemente. Este servidor almacena las credenciales de tantas cuentas de Gmail como autorice y enruta cada llamada a la que usted indique.

Related MCP server: multiGmailMCP

Requisitos

• Node.js 20 o una versión más reciente

• Un proyecto de Google Cloud con la API de Gmail habilitada y un cliente OAuth de tipo Aplicación de escritorio

1. Obtenga un cliente OAuth de Google

1. Abra la Google Cloud Console y seleccione o cree un proyecto.

2. APIs y servicios → Biblioteca → habilite la API de Gmail.

3. APIs y servicios → Pantalla de consentimiento de OAuth → configúrela. Mientras la aplicación esté en modo de pruebas, añada todas las direcciones de Gmail que planee conectar en Usuarios de prueba.

4. APIs y servicios → Credenciales → Crear credenciales → ID de cliente de OAuth → tipo de aplicación Aplicación de escritorio. Descargue el archivo JSON.

Los clientes de aplicación de escritorio permiten redirecciones de bucle local en cualquier puerto, que es lo que usa el flujo add-account.

2. Instale y compile

git clone <this repo>
cd Gmail-MCP
npm install
npm run build

3. Apunte el servidor a su cliente OAuth

Elija una opción:

# Option A — save the downloaded JSON where the server looks by default
mkdir -p ~/.gmail-mcp && cp ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json

# Option B — point at it explicitly
export GMAIL_MCP_CREDENTIALS=/path/to/client_secret.json

# Option C — pass the values directly
export GMAIL_MCP_CLIENT_ID=...apps.googleusercontent.com
export GMAIL_MCP_CLIENT_SECRET=...

4. Autorice cada buzón

Ejecute una vez por cuenta de Gmail:

node dist/index.js add-account --alias work
node dist/index.js add-account --alias personal
node dist/index.js list-accounts

Cada ejecución imprime una URL de consentimiento de Google, espera en un puerto de bucle local la redirección y guarda el token de actualización resultante. En una máquina sin interfaz gráfica, añada --manual y pegue la URL de redirección.

Las cuentas añadidas mientras el servidor está en ejecución se detetan automáticamente: no es necesario reiniciar.

5. Conéctelo a Claude

Claude Code

claude mcp add gmail-multi -- node /absolute/path/to/Gmail-MCP/dist/index.js

Claude Desktop — añada la configuración a claude_desktop_config.json:

{
  "mcpServers": {
    "gmail-multi": {
      "command": "node",
      "args": ["/absolute/path/to/Gmail-MCP/dist/index.js"],
      "env": {
        "GMAIL_MCP_CREDENTIALS": "/absolute/path/to/client_secret.json"
      }
    }
  }
}

Selección de una cuenta

Todas las herramientas excepto list_accounts aceptan account. Se busca la coincidencia, en este orden:

1. la dirección de correo completa — mikael@example.com

2. el alias definido al ejecutar add-account — work

3. la parte local anterior a @ — mikael

4. cualquier prefijo inequívoco

account es opcional cuando solo hay un buzón configurado o cuando GMAIL_MCP_DEFAULT_ACCOUNT está definida. De lo contrarío, es obligatorio y el error enumera lo disponible.

Los ID son específicos de cada buzón. El ID de un mensaje, hilo, borrador o etiqueta de una cuenta no significa nada en otra. Un error de «no encontrado» suele significar que se ha pasado una account equivocada.

Herramientas

35 herramientas: las del conector más dos para varias cuentas.

Los nombres de las herramientas coinciden deliberadamente con los del conector de Gmail, de modo que las indicaciones y los hábitos se conservan. Los clientes MCP organizan las herramientas en espacios de nombres por servidor, por lo que ambos pueden estar habilitados a la vez sin colisiones.

Diferencias respecto al conector integrado

Todo lo siguiente es adicional: nada de lo que hace el conector se comporta de forma diferente aquí.

• account en todas las herramientas, además de list_accounts y get_profile.

• response_format (markdown | json) en cada herramienta. markdown es el valor por defecto y se mantiene compacto; la carga útil estructurada completa se devuelve como structuredContent en ambos casos.

• delete_draft y get_message_attachment, que el conector menciona pero no expone.

• reply acepta quoteOriginal (por defecto false) para añadir el original como un bloque citado.

• forward acepta includeAttachments (por defecto true); establézcalo en false para omitir archivos grandes.

• get_message_attachment acepta savePath para escribir un archivo en disco en lugar de incrustar base64.

• Las respuestas están limitadas a 25 000 caracteres; primero se reducen las listas paginadas y se indica exactamente qué se ha omitido y cómo obtener el resto.

Comportamientos que conviene conocer

• search_threads devuelve una vista previa de los mensajes más antiguos de cada hilo (~5), al igual que el conector. Llame a get_thread antes de responder nada sobre el correo reciente o no leído.

• Los borradores se excluyen de search_threads a menos que la consulta mencione borradores. Use list_drafts.

• Las etiquetas se identifican por ID, no por el nombre para mostrar. Llame primero a list_labels.

• DRAFT y SENT son de solo lectura; añadir TRASH/SPAM se canaliza a las herramientas apply_sensitive_* para que las acciones destructivas siempre se nombren explícitamente.

• update_draft fusina campos, pero los adjuntos se reemplazan, no se fusionan — la respuesta informa de cuántos se han descartado.

• reply establece In-Reply-To y References para que los clientes gestionen el hilo correctamente, y nunca dirige la respuesta al propio buzón autorizado.

Seguridad

• Los tokens de actualización residen en ~/.gmail-mcp/accounts.json, escritos atómicamente con permisos 0600 dentro de un directorio con permisos 0700. Cualquiera con acceso de lectura a ese archivo tiene acceso completo a los buzones.

• El flujo de OAuth valida el parámetro state y escucha solo en 127.0.0.1.

• remove-account elimina el token local. Para revocar el acceso por completo, elimine también la aplicación en myaccount.google.com/permissions.

• Los alcances otorgados permiten leer, enviar y eliminar correo. send_message, reply y forward entregan el correo de inmediato; las descripciones de las herramientas indican al modelo que prefiera create_draft cuando el usuario no haya pedido claramente que el correo salga.

Desarrollo

npm run build         # compile TypeScript to dist/
npm test              # build, then unit tests + stdio smoke test
npm run test:unit     # MIME, reply addressing, parsing, truncation — no network
npm run test:smoke    # boots the server, checks all 35 tools register
npm run inspect       # open the MCP Inspector against the server

src/
  index.ts            CLI entry point and server bootstrap
  constants.ts        scopes, limits, paths
  types.ts            normalized message/thread/draft shapes
  auth/               token store, OAuth flow, account registry
  schemas/common.ts   shared Zod fields (account, formats, pagination, colors)
  services/           Gmail parsing, MIME building, formatting, errors
  tools/              tool registration by domain

Solución de problemas

Licencia

MIT