mcp-hey

Servidor MCP local para el correo de Hey.com: leer, buscar, enviar, responder y gestionar el screener mediante cookies de sesión almacenadas.

GitHub

Prueba este MCPPatrocinado

Documentación

mcp-hey

Un servidor local de Model Context Protocol (MCP) que le da 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 herramientas de Hey a través de stdio, y un pequeño ayudante de Python que usa la webview del sistema para capturar cookies de sesión al iniciar sesión. Todo se ejecuta localmente — sin relé en la nube, sin credenciales almacenadas, solo cookies de sesión en disco.

Advertencia — API no oficial. Hey.com no publica una API pública; mcp-hey aplica ingeniería inversa a 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 de Imbox, Feed, Paper Trail, Set Aside, Reply Later, Drafts, Trash y Spam
Descargar adjuntos y analizar invitaciones de calendario de los correos
Enviar y responder a hilos de correo
Buscar correos en todas las bandejas
Organizar el correo (apartar, responder después, filtrar dentro/fuera, burbujear)
Caché local 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 quieres 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 ha probado actualmente.

Instalación

Clona este repositorio

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

Instala las dependencias

bun install
uv pip install -r auth/requirements.txt

Primera ejecución — autenticación
```
bun run dev
```
1. Se abre una webview del sistema con la página de inicio de sesión de Hey.com. Inicia sesión normalmente.
2. El ayudante captura las cookies de sesión en data/hey-cookies.json (permisos 600) y sale.
3. Pulsa Ctrl+C — tu cliente MCP lanzará su propia instancia del servidor a partir de ahora.
4. Las ejecuciones posteriores reutilizan la sesión almacenada hasta que expire.

Configuración del cliente MCP

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

Claude Code

La vía 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, añade a .mcp.json en la raíz de tu proyecto (o ~/.claude.json para un servidor a nivel 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 tome.

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.

Docker

Se incluye un Dockerfile para despliegues contenerizados y compatibilidad con Glama.

Construye la imagen:

docker build -t mcp-hey .

Prueba rápida del servidor (debería devolver una respuesta JSON-RPC que liste las herramientas disponibles):

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

Nota: La imagen Docker ejecuta solo el servidor MCP. El ayudante de autenticación de Python y el inicio de sesión por webview 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 lanzados por Claude Code no siempre heredan el PATH de tu terminal interactivo, por lo que un bun instalado con Homebrew puede fallar con spawn bun ENOENT o simplemente no 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 encontrarlo

Ejemplo:

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

Arquitectura

Componente	Descripción
Servidor MCP	Bun/TypeScript, transporte stdio, ~30 MB de memoria en reposo
Ayudante de autenticación	Python/pywebview, se lanza bajo demanda para iniciar sesión mediante webview del sistema
Caché	Almacén local SQLite para mensajes, hilos e índice de búsqueda
Comunicación	Compartición de sesión basada en archivos mediante `data/hey-cookies.json`

Flujo de datos

El cliente MCP (Claude Code, Claude Desktop, Cursor, etc.) lanza bun run src/index.ts a través de stdio.
Al iniciar, el servidor valida data/hey-cookies.json. Si falta o ha expirado, lanza auth/hey-auth.py, que abre Hey en una webview del sistema y escribe cookies nuevas.
Las llamadas a herramientas golpean Hey.com directamente con cabeceras realistas de navegador; las respuestas se analizan (HTML mediante node-html-parser) y se almacenan en caché en SQLite.
Las operaciones de escritura obtienen un token CSRF nuevo antes de enviar.

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 (34 tools)
    hey-features-doc.md  # Hey.com feature mapping

Herramientas disponibles

34 herramientas agrupadas por función. Consulta docs/TOOLS.md para parámetros, formas de retorno y comportamiento de errores.

Categoría	Herramientas
Lectura	`hey_list_emails` (imbox, feed, paper_trail, trash, spam, drafts), `hey_imbox_summary`, `hey_list_set_aside`, `hey_list_reply_later`, `hey_list_screener`, `hey_read_email`, `hey_download_attachment`, `hey_get_calendar_invite`
Etiquetas y colecciones	`hey_list_labels`, `hey_list_label_emails`, `hey_label`, `hey_list_collections`, `hey_list_collection_emails`, `hey_collection`
Envío	`hey_send_email`, `hey_reply`, `hey_forward`
Triaje	`hey_set_aside`, `hey_unset_aside`, `hey_reply_later`, `hey_remove_reply_later`, `hey_move_to`, `hey_set_status`, `hey_mark_unseen`, `hey_mark_seen`, `hey_read_status`, `hey_thread_mute`
Elevar	`hey_bubble_up`, `hey_bubble_up_if_no_reply`, `hey_pop_bubble`
Filtro	`hey_screen`, `hey_screen_by_id`
Búsqueda	`hey_search`
Caché	`hey_cache_status`

Privacidad y seguridad

Nunca se almacenan credenciales — solo cookies de sesión, escritas con permisos 600.
La autenticación ocurre completamente dentro de la página de inicio de sesión de Hey (webview del sistema).
Todos los datos permanecen en tu máquina. Este proyecto no emite telemetría.
MCP usa transporte stdio — el servidor nunca abre un listener de red.
La validez de la sesión se comprueba al iniciar y antes de operaciones sensibles.

Consulta SECURITY.md para saber cómo reportar vulnerabilidades.

Limitaciones

Riesgo de inyección de prompts: como muchos servidores MCP, este está sujeto a la tríada letal. Un correo malicioso que llegue a tu bandeja de entrada podría intentar instruir a Claude para exfiltrar otros mensajes. Trata la superficie de herramientas 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 deltas conocidos.
Sin notificaciones en tiempo real: solo sondeo.
La subida de adjuntos aún no está soportada.
Cuenta única por instancia del servidor MCP.
Riesgo de cuenta: los patrones de acceso agresivos o anormales podrían en teoría activar los sistemas antiabuso 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 un idioma distinto del inglés.

Solución de problemas

La webview de autenticación no se abre — confirma que Python 3.10+ está en PATH y que uv pip install -r auth/requirements.txt se ejecutó correctamente. En Linux asegúrate de que haya un backend de webview 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 expirado. Elimina data/hey-cookies.json y ejecuta bun run dev de nuevo para reautenticarte.
Límites de tasa (429) — el cliente respeta las cabeceras x-ratelimit y retrocede. Si ves 429s sostenidos, reduce el uso concurrente de herramientas o espera unos minutos.
El cliente MCP no puede lanzar 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 cookies de sesión antes (por ejemplo, _hey_session → session_token, consulta el changelog docs/API.md). Si la autenticación falla silenciosamente después de una actualización de Hey, captura cookies nuevas y compara.

Contribuciones

Las contribuciones son bienvenidas mediante 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 (impulsado por Biome).
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 el flujo de trabajo de desarrollo completo.

Licencia

Licencia MIT — consulta LICENCE.

mcp-hey

Documentación

mcp-hey

Características

Configuración

Requisitos previos

Instalación

Configuración del cliente MCP

Claude Code

Claude Desktop

Cursor

Docker

macOS: bun PATH

Arquitectura

Flujo de datos

Estructura del proyecto

Herramientas disponibles

Privacidad y seguridad

Limitaciones

Solución de problemas

Contribuciones

Licencia

macOS: `bun` PATH