mcp-hey

Servidor MCP local para e-mail do Hey.com - ler, pesquisar, enviar, responder e gerenciar o screener via cookies de sessão armazenados.

GitHub

Experimente este MCPPatrocinado

Documentação

mcp-hey

Um servidor local de Model Context Protocol (MCP) que dá ao Claude acesso de leitura/escrita à sua caixa de entrada do Hey.com por meio de APIs web de engenharia reversa.

O mcp-hey tem duas partes móveis: um servidor MCP em Bun/TypeScript que expõe ferramentas do Hey via stdio, e um pequeno auxiliar em Python que usa o webview do sistema para capturar cookies de sessão no login. Tudo roda localmente — sem relay em nuvem, sem armazenamento de credenciais, apenas cookies de sessão no disco.

Aviso — API não oficial. O Hey.com não publica uma API pública; o mcp-hey faz engenharia reversa de seus endpoints web e os combina com requisições HTTP idênticas às do navegador. As coisas podem quebrar sem aviso. A superfície documentada atual está em docs/API.md.

Recursos

Ler e-mails de Imbox, Feed, Paper Trail, Set Aside, Reply Later, Drafts, Trash e Spam
Baixar anexos e analisar convites de calendário de e-mails
Enviar e responder a threads de e-mail
Pesquisar e-mails entre caixas
Organizar correspondência (set aside, reply later, screen in/out, bubble up)
Cache local em SQLite para leituras repetidas mais rápidas e busca em texto completo
Leve — cerca de 30 MB de memória ociosa
Cabeçalhos idênticos aos do navegador e postura TLS para evitar detecção
Roda inteiramente na sua máquina; transporte stdio sem exposição de rede

Configuração

Pré-requisitos

Bun 1.1 ou posterior
Python 3.10 ou posterior (mais UV se quiser seguir as ferramentas Python em CLAUDE.md)
Uma conta no Hey.com
Plataforma: desenvolvido e testado em macOS e Linux. Usuários de Windows provavelmente precisarão de WSL — o backend Windows do pywebview não é exercitado atualmente.

Instalação

Clone este repositório

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

Instale as dependências

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

Primeira execução — autentique
```
bun run dev
```
1. Um webview do sistema abre com a página de login do Hey.com. Faça login normalmente.
2. O auxiliar captura cookies de sessão para data/hey-cookies.json (permissões 600) e sai.
3. Pressione Ctrl+C — seu cliente MCP iniciará sua própria instância do servidor a partir daqui.
4. Execuções subsequentes reutilizam a sessão armazenada até que expire.

Configuração do cliente MCP

Todos os clientes abaixo usam a mesma forma command/args. No macOS, você quase certamente precisará do caminho absoluto para bun — veja macOS: bun PATH abaixo.

Claude Code

O caminho mais rápido é a CLI:

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

O servidor está disponível imediatamente na sessão atual.

Alternativamente, adicione a .mcp.json na raiz do seu projeto (ou ~/.claude.json para um servidor com escopo de usuário):

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

Se você editar o arquivo diretamente, reinicie a sessão do Claude Code para aplicar as mudanças.

Claude Desktop

Adicione a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

Reinicie o Claude Desktop. Você deve ver hey listado como uma integração disponível.

Cursor

Adicione a ~/.cursor/mcp.json:

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

Reinicie o Cursor.

Docker

Um Dockerfile está incluído para implantações em contêineres e compatibilidade com Glama.

Construa a imagem:

docker build -t mcp-hey .

Teste o servidor (deve retornar uma resposta JSON-RPC listando as ferramentas disponíveis):

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

Nota: A imagem Docker executa apenas o servidor MCP. O auxiliar de autenticação Python e o login via webview não estão disponíveis dentro do contêiner. Você deve fornecer cookies de sessão pré-existentes via montagem de volume em data/hey-cookies.json para operações autenticadas.

macOS: `bun` PATH

Aplicativos GUI (Claude Desktop, Cursor) e shells iniciados pelo Claude Code nem sempre herdam o PATH do seu terminal interativo, então um bun instalado via Homebrew pode falhar com spawn bun ENOENT ou simplesmente nunca conectar. Corrija usando o caminho absoluto para bun em command:

Homebrew Apple Silicon — /opt/homebrew/bin/bun
Homebrew Intel — /usr/local/bin/bun
Instalação manual — execute which bun no seu terminal para encontrá-lo

Exemplo:

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

Arquitetura

Componente	Descrição
Servidor MCP	Bun/TypeScript, transporte stdio, ~30 MB de memória ociosa
Auxiliar de autenticação	Python/pywebview, iniciado sob demanda para login via webview do sistema
Cache	Armazenamento local em SQLite para mensagens, threads e índice de busca
Comunicação	Compartilhamento de sessão baseado em arquivos via `data/hey-cookies.json`

Fluxo de dados

O cliente MCP (Claude Code, Claude Desktop, Cursor, etc.) inicia bun run src/index.ts via stdio.
Na inicialização, o servidor valida data/hey-cookies.json. Se ausente ou expirado, ele inicia auth/hey-auth.py, que abre o Hey em um webview do sistema e grava cookies novos.
Chamadas de ferramentas acessam o Hey.com diretamente com cabeçalhos realistas de navegador; as respostas são analisadas (HTML via node-html-parser) e armazenadas em cache no SQLite.
Operações de escrita buscam um token CSRF novo antes de enviar.

Estrutura do projeto

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

Ferramentas disponíveis

34 ferramentas agrupadas por função. Veja docs/TOOLS.md para parâmetros, formatos de retorno e comportamento de erros.

Categoria	Ferramentas
Leitura	`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`
Rótulos e Coleções	`hey_list_labels`, `hey_list_label_emails`, `hey_label`, `hey_list_collections`, `hey_list_collection_emails`, `hey_collection`
Envio	`hey_send_email`, `hey_reply`, `hey_forward`
Triagem	`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`
Bubble up	`hey_bubble_up`, `hey_bubble_up_if_no_reply`, `hey_pop_bubble`
Screener	`hey_screen`, `hey_screen_by_id`
Busca	`hey_search`
Cache	`hey_cache_status`

Privacidade e segurança

Nenhuma credencial é armazenada — apenas cookies de sessão, gravados com permissões 600.
A autenticação acontece inteiramente na própria página de login do Hey (webview do sistema).
Todos os dados permanecem na sua máquina. Nenhuma telemetria é emitida por este projeto.
O MCP usa transporte stdio — o servidor nunca abre um listener de rede.
A validade da sessão é verificada na inicialização e antes de operações sensíveis.

Veja SECURITY.md para saber como relatar vulnerabilidades.

Limitações

Risco de injeção de prompt: como muitos servidores MCP, este está sujeito à tríade letal. Um e-mail malicioso que chegar à sua caixa de entrada pode tentar instruir o Claude a exfiltrar outras mensagens. Trate a superfície de ferramentas de acordo e revise ações arriscadas antes de aprová-las.
API não oficial: o frontend do Hey.com pode mudar sem aviso e quebrar coisas. Espere quebras ocasionais e verifique docs/API.md para deltas conhecidos.
Sem notificações em tempo real: apenas polling.
Upload de anexos ainda não é suportado.
Conta única por instância do servidor MCP.
Risco de conta: padrões de acesso agressivos ou anormais podem, em teoria, acionar os sistemas anti-abuso do Hey. O servidor respeita cabeçalhos x-ratelimit e faz backoff exponencial, mas não há garantias.
Interface em inglês apenas: o servidor analisa as respostas HTML do Hey.com e corresponde a strings em inglês (ex.: "You ignored this thread", nomes de rótulos, texto de botões). Não funcionará corretamente se o Hey.com estiver configurado para um idioma diferente do inglês.

Solução de problemas

O webview de autenticação não abre — confirme que o Python 3.10+ está no PATH e que uv pip install -r auth/requirements.txt foi bem-sucedido. No Linux, garanta que um backend de webview esteja disponível (python -c "import webview" não deve gerar erro).
Respostas 401/403 após semanas de uso — sua sessão do Hey expirou. Exclua data/hey-cookies.json e execute bun run dev novamente para reautenticar.
Limites de taxa (429) — o cliente respeita cabeçalhos x-ratelimit e faz backoff. Se você vir 429s sustentados, reduza o uso concorrente de ferramentas ou aguarde alguns minutos.
O cliente MCP não consegue iniciar o servidor — args deve ser um caminho absoluto, não relativo. Se bun falhar com spawn bun ENOENT, veja macOS: bun PATH.
Nome do cookie alterado — o Hey já renomeou cookies de sessão antes (ex.: _hey_session → session_token, veja o changelog docs/API.md). Se a autenticação falhar silenciosamente após uma atualização do Hey, capture cookies novos e compare.

Contribuindo

Contribuições são bem-vindas via pull request. Por favor:

Use commits convencionais (feat, fix, docs, refactor, test, perf, cicd, revert, WIP).
Execute bun run format e bun run lint antes de enviar (alimentado por Biome).
Garanta que bun test passe.
Atualize docs/API.md se você descobrir ou alterar qualquer comportamento da API do Hey.com.

Veja CLAUDE.md para o fluxo de desenvolvimento completo.

Licença

Licença MIT — veja LICENCE.

mcp-hey

Documentação

mcp-hey

Recursos

Configuração

Pré-requisitos

Instalação

Configuração do cliente MCP

Claude Code

Claude Desktop

Cursor

Docker

macOS: bun PATH

Arquitetura

Fluxo de dados

Estrutura do projeto

Ferramentas disponíveis

Privacidade e segurança

Limitações

Solução de problemas

Contribuindo

Licença

macOS: `bun` PATH