mcp-hey

Un servidor local del Protocolo de Contexto de Modelo (MCP) que otorga a Claude acceso de lectura/escritura a tu bandeja de entrada de Hey.com mediante APIs web de ingeniería inversa.

mcp-hey tiene dos partes móviles: un servidor MCP en Bun/TypeScript que expone las herramientas de Hey a través de stdio, y un pequeño asistente en Python que utiliza la vista web del sistema para capturar cookies de sesión al iniciar sesión. Todo se ejecuta localmente: sin retransmisión en la nube, sin credenciales almacenadas, solo cookies de sesión en el disco.

Atención: API no oficial. Hey.com no publica una API pública; mcp-hey realiza ingeniería inversa de sus endpoints web y los combina con solicitudes HTTP idénticas a las del navegador. Las cosas pueden romperse sin previo aviso. La superficie documentada actual se encuentra en docs/API.md.

Características

• Leer correos electrónicos de Imbox, Feed, Paper Trail, Set Aside y Reply Later

• Enviar y responder a hilos de correo electrónico

• Buscar correos electrónicos en todas las bandejas

• Organizar el correo (apartar, responder más tarde, filtrar dentro/fuera, destacar)

• Caché local de SQLite para lecturas repetidas más rápidas y búsqueda de texto completo

• Ligero: alrededor de 30 MB de memoria en reposo

• Cabeceras y postura TLS idénticas a las del navegador para evitar la detección

• Se ejecuta completamente en tu máquina; transporte stdio sin exposición a la red

Configuración

Requisitos previos

• Bun 1.1 o posterior

• Python 3.10 o posterior (además de UV si deseas seguir las herramientas de Python en CLAUDE.md)

• Una cuenta de Hey.com

• Plataforma: desarrollado y probado en macOS y Linux. Los usuarios de Windows probablemente necesitarán WSL; el backend de Windows de pywebview no se utiliza actualmente.

Instalación

1. Clona este repositorio

   git clone https://github.com/Sealjay/mcp-hey.git
   cd mcp-hey

2. Instala las dependencias

   bun install
   pip install -r auth/requirements.txt

3. Primera ejecución: autenticación

   bun run dev

   El asistente de autenticación de Python abre una vista web del sistema apuntando a Hey.com. Inicia sesión normalmente; el asistente captura las cookies de sesión en data/hey-cookies.json (permisos bloqueados en 600) y se cierra. Las ejecuciones posteriores reutilizan la sesión almacenada hasta que caduca.

Configuración del cliente MCP

Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "hey": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/mcp-hey/src/index.ts"]
    }
  }
}

Reinicia Claude Desktop. Deberías ver hey listado como una integración disponible.

Cursor

Añade a ~/.cursor/mcp.json:

{
  "mcpServers": {
    "hey": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/mcp-hey/src/index.ts"]
    }
  }
}

Reinicia Cursor.

Arquitectura

Flujo de datos

1. El cliente MCP (Claude Desktop / Cursor) inicia bun run src/index.ts a través de stdio.

2. Al iniciarse, el servidor valida data/hey-cookies.json. Si falta o ha caducado, inicia auth/hey-auth.py, que abre Hey en una vista web del sistema y escribe cookies nuevas.

3. Las llamadas a herramientas llegan directamente a Hey.com con cabeceras realistas de navegador; las respuestas se analizan (HTML a través de node-html-parser) y se almacenan en caché en SQLite.

4. Las operaciones de escritura obtienen un token CSRF nuevo antes de enviarse.

Estructura del proyecto

mcp-hey/
  src/
    index.ts           # MCP server entry point
    hey-client.ts      # HTTP client with cookie injection
    session.ts         # Session management and validation
    errors.ts          # Error classes and sanitisation
    cache/             # SQLite cache (db, schema, messages, search)
    tools/             # MCP tool implementations
      read.ts          # Reading and listing
      send.ts          # Send, reply, forward
      organise.ts      # Triage, labels, bubble up, etc.
      http-helpers.ts  # Shared CSRF retry and endpoint fallback
    __tests__/         # Test suites
  auth/
    hey-auth.py        # Python auth helper (pywebview)
    requirements.txt
  data/
    hey-cookies.json   # Session storage (gitignored, chmod 600)
  docs/
    API.md             # Hey.com API surface documentation
    TOOLS.md           # MCP tool reference (41 tools)

Herramientas disponibles

41 herramientas agrupadas por función. Consulta docs/TOOLS.md para conocer los parámetros, las formas de retorno y el comportamiento ante errores.

Privacidad y seguridad

• Nunca se almacenan credenciales, solo cookies de sesión, escritas con permisos 600.

• La autenticación ocurre completamente dentro de la propia página de inicio de sesión de Hey (vista web del sistema).

• Todos los datos permanecen en tu máquina. Este proyecto no emite telemetría.

• MCP utiliza transporte stdio: el servidor nunca abre un oyente de red.

• La validez de la sesión se verifica al inicio y antes de operaciones sensibles.

Consulta SECURITY.md para saber cómo informar de vulnerabilidades.

Limitaciones

• Riesgo de inyección de prompts: como ocurre con muchos servidores MCP, este está sujeto a la tripleta letal. Un correo electrónico malicioso que llegue a tu bandeja de entrada podría intentar instruir a Claude para que exfiltre otros mensajes. Trata la superficie de la herramienta en consecuencia y revisa las acciones arriesgadas antes de aprobarlas.

• API no oficial: el frontend de Hey.com puede cambiar sin previo aviso y romper cosas. Espera roturas ocasionales y consulta docs/API.md para conocer los cambios conocidos.

• Sin notificaciones en tiempo real: solo sondeo (polling).

• La carga de archivos adjuntos aún no es compatible.

• Una sola cuenta por instancia de servidor MCP.

• Riesgo de cuenta: los patrones de acceso agresivos o anormales podrían, en teoría, activar los sistemas anti-abuso de Hey. El servidor respeta las cabeceras x-ratelimit y retrocede exponencialmente, pero no hay garantías.

Solución de problemas

• La vista web de autenticación no se abre: confirma que Python 3.10+ está en el PATH y que pip install -r auth/requirements.txt se realizó correctamente. En Linux, asegúrate de que haya un backend de vista web disponible (python -c "import webview" no debería dar error).

• Respuestas 401/403 después de semanas de uso: tu sesión de Hey ha caducado. Elimina data/hey-cookies.json y ejecuta bun run dev de nuevo para volver a autenticarte.

• Límites de tasa (429): el cliente respeta las cabeceras x-ratelimit y retrocede. Si ves 429 sostenidos, reduce el uso concurrente de herramientas o espera unos minutos.

• Bun no puede encontrar el script en Claude Desktop/Cursor: la ruta args debe ser absoluta, no relativa, y bun debe ser detectable desde el entorno de inicio del cliente (en macOS esto puede significar usar una ruta completa como /opt/homebrew/bin/bun).

• El nombre de la cookie cambió: Hey ha renombrado las cookies de sesión anteriormente (por ejemplo, _hey_session → session_token, consulta CLAUDE.md para ver el registro). Si la autenticación falla silenciosamente después de una actualización de Hey, captura cookies nuevas y compáralas.

Contribución

Las contribuciones son bienvenidas a través de pull request. Por favor:

• Usa commits convencionales (feat, fix, docs, refactor, test, perf, cicd, revert, WIP).

• Ejecuta bun run format y bun run lint antes de hacer push.

• Asegúrate de que bun test pase.

• Actualiza docs/API.md si descubres o cambias cualquier comportamiento de la API de Hey.com.

Consulta CLAUDE.md para conocer el flujo de trabajo de desarrollo completo.

Licencia

Licencia MIT: consulta LICENCE.