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

Advertencia: 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, Reply Later, Drafts, Trash y Spam

• Descargar archivos adjuntos y analizar invitaciones de calendario de los correos electrónicos

• 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 idénticas a las del navegador y postura TLS para evitar la detección

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

Related MCP server: email-mcp

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
   uv pip install -r auth/requirements.txt

3. Primera ejecución: autenticación

   bun run dev

   1. Se abre una vista web del sistema con la página de inicio de sesión de Hey.com. Inicia sesión normalmente.

   2. El asistente captura las cookies de sesión en data/hey-cookies.json (permisos 600) y se cierra.

   3. Presiona Ctrl+C: tu cliente MCP iniciará su propia instancia del servidor a partir de ahora.

   4. Las ejecuciones posteriores reutilizan la sesión almacenada hasta que caduca.

Configuración del cliente MCP

Todos los clientes a continuación utilizan la misma forma de command/args. En macOS, casi con seguridad necesitarás la ruta absoluta a bun: consulta macOS: bun PATH a continuación.

Claude Code

La ruta más rápida es la CLI:

claude mcp add --transport stdio hey --scope user -- bun run /absolute/path/to/mcp-hey/src/index.ts

El servidor está disponible inmediatamente en la sesión actual.

Alternativamente, agrégalo a .mcp.json en la raíz de tu proyecto (o ~/.claude.json para un servidor con alcance de usuario):

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

Si editas el archivo directamente, reinicia la sesión de Claude Code para que lo detecte.

Claude Desktop

Agrégalo 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

Agrégalo a ~/.cursor/mcp.json:

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

Reinicia Cursor.

Docker

Se incluye un Dockerfile para implementaciones en contenedores y compatibilidad con Glama.

Construye la imagen:

docker build -t mcp-hey .

Prueba de humo del servidor (debería devolver una respuesta JSON-RPC listando las herramientas disponibles):

printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | docker run -i mcp-hey

Nota: La imagen de Docker solo ejecuta el servidor MCP. El asistente de autenticación de Python y el inicio de sesión en la vista web no están disponibles dentro del contenedor. Debes proporcionar cookies de sesión preexistentes mediante un montaje de volumen en data/hey-cookies.json para operaciones autenticadas.

macOS: bun PATH

Las aplicaciones GUI (Claude Desktop, Cursor) y los shells iniciados por Claude Code no siempre heredan el PATH de tu terminal interactiva, por lo que un bun instalado con Homebrew puede fallar con spawn bun ENOENT o simplemente nunca conectarse. Soluciónalo usando la ruta absoluta a bun en command:

• Apple Silicon Homebrew — /opt/homebrew/bin/bun

• Intel Homebrew — /usr/local/bin/bun

• Instalación manual — ejecuta which bun en tu terminal para encontrarla

Ejemplo:

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

Arquitectura

Flujo de datos

1. El cliente MCP (Claude Code, Claude Desktop, Cursor, etc.) inicia bun run src/index.ts sobre stdio.

2. Al inicio, 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 mediante 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
      attachments.ts   # Download attachments, parse calendar invites
    __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 (33 tools)
    hey-features-doc.md  # Hey.com feature mapping

Herramientas disponibles

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

• Las subidas de archivos adjuntos aún no son compatibles.

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

• Solo interfaz en inglés: el servidor analiza las respuestas HTML de Hey.com y coincide con cadenas en inglés (por ejemplo, "You ignored this thread", nombres de etiquetas, texto de botones). No funcionará correctamente si Hey.com está configurado en una configuración regional que no sea inglés.

Solución de problemas

• La vista web de autenticación no se abre: confirma que Python 3.10+ está en el PATH y que uv pip install -r auth/requirements.txt tuvo éxito. 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.

• El cliente MCP no puede iniciar el servidor: args debe ser una ruta absoluta, no relativa. Si bun falla con spawn bun ENOENT, consulta macOS: bun PATH.

• El nombre de la cookie cambió: Hey ha renombrado las cookies de sesión anteriormente (por ejemplo, _hey_session → session_token, consulta el registro de cambios en docs/API.md). Si la autenticación falla silenciosamente después de una actualización de Hey, captura cookies nuevas y compara.

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 enviar (impulsado por Biome).

• Asegúrate de que bun test pase.

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

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

Licencia

Licencia MIT: consulta LICENCE.