mcp-hey

Claude가 Hey.com 받은 편지함에 리버스 엔지니어링된 웹 API를 통해 읽기/쓰기 권한을 가질 수 있도록 하는 로컬 MCP(Model Context Protocol) 서버입니다.

mcp-hey는 두 가지 핵심 요소로 구성됩니다. Hey 도구를 stdio를 통해 노출하는 Bun/TypeScript MCP 서버와, 로그인 시 시스템 웹뷰를 사용하여 세션 쿠키를 캡처하는 작은 Python 도우미입니다. 모든 작업은 로컬에서 실행되며 클라우드 릴레이를 사용하지 않고, 자격 증명을 저장하지 않으며, 디스크에 세션 쿠키만 저장합니다.

경고 — 비공식 API. Hey.com은 공개 API를 제공하지 않습니다. mcp-hey는 웹 엔드포인트를 리버스 엔지니어링하여 브라우저와 동일한 HTTP 요청을 수행합니다. 예고 없이 기능이 중단될 수 있습니다. 현재 문서화된 인터페이스는 docs/API.md에서 확인할 수 있습니다.

기능

• Imbox, Feed, Paper Trail, Set Aside, Reply Later, Drafts, Trash, Spam에서 이메일 읽기

• 이메일에서 첨부 파일 다운로드 및 캘린더 초대 파싱

• 이메일 스레드 보내기 및 답장

• 편지함 전체에서 이메일 검색

• 메일 정리 (set aside, reply later, screen in/out, bubble up)

• 더 빠른 반복 읽기 및 전체 텍스트 검색을 위한 로컬 SQLite 캐시

• 경량화 — 유휴 상태에서 약 30MB 메모리 사용

• 탐지를 피하기 위한 브라우저와 동일한 헤더 및 TLS 설정

• 전적으로 사용자 기기에서 실행; 네트워크 노출이 없는 stdio 전송 방식

Related MCP server: email-mcp

설정

필수 조건

• Bun 1.1 이상

• Python 3.10 이상 (CLAUDE.md의 Python 도구를 사용하려면 UV 필요)

• Hey.com 계정

• 플랫폼: macOS 및 Linux에서 개발 및 테스트되었습니다. Windows 사용자는 WSL이 필요할 수 있습니다. (pywebview의 Windows 백엔드는 현재 테스트되지 않았습니다.)

설치

1. 저장소 복제

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

2. 의존성 설치

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

3. 첫 실행 — 인증

   bun run dev

   1. Hey.com 로그인 페이지가 포함된 시스템 웹뷰가 열립니다. 정상적으로 로그인하세요.

   2. 도우미가 세션 쿠키를 data/hey-cookies.json (권한 600)에 캡처하고 종료됩니다.

   3. Ctrl+C를 누르세요. 이후부터는 MCP 클라이언트가 자체적으로 서버 인스턴스를 실행합니다.

   4. 이후 실행 시에는 세션이 만료될 때까지 저장된 세션을 재사용합니다.

MCP 클라이언트 설정

아래의 모든 클라이언트는 동일한 command/args 형식을 사용합니다. macOS에서는 거의 확실히 bun의 절대 경로가 필요합니다. 아래 macOS: bun PATH를 참조하세요.

Claude Code

가장 빠른 방법은 CLI를 사용하는 것입니다:

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

서버는 현재 세션에서 즉시 사용할 수 있습니다.

또는 프로젝트 루트의 .mcp.json (또는 사용자 범위 서버의 경우 ~/.claude.json)에 추가하세요:

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

파일을 직접 수정하는 경우, Claude Code 세션을 재시작하여 변경 사항을 적용하세요.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS)에 추가하세요:

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

Claude Desktop을 재시작하세요. 사용 가능한 통합 기능 목록에 hey가 표시되어야 합니다.

Cursor

~/.cursor/mcp.json에 추가하세요:

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

Cursor를 재시작하세요.

Docker

컨테이너 배포 및 Glama 호환성을 위해 Dockerfile이 포함되어 있습니다.

이미지 빌드:

docker build -t mcp-hey .

서버 스모크 테스트 (사용 가능한 도구 목록이 포함된 JSON-RPC 응답이 반환되어야 함):

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

참고: Docker 이미지는 MCP 서버만 실행합니다. Python 인증 도우미 및 웹뷰 로그인은 컨테이너 내부에서 사용할 수 없습니다. 인증된 작업을 수행하려면 기존 세션 쿠키를 data/hey-cookies.json으로 볼륨 마운트해야 합니다.

macOS: bun PATH

GUI 앱(Claude Desktop, Cursor) 및 Claude Code가 실행하는 셸은 대화형 터미널의 PATH를 항상 상속받지 않으므로, Homebrew로 설치된 bun이 spawn bun ENOENT 오류를 발생시키거나 연결되지 않을 수 있습니다. command에 bun의 절대 경로를 사용하여 해결하세요:

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

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

• 수동 설치 — 터미널에서 which bun을 실행하여 경로를 찾으세요

예시:

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

아키텍처

데이터 흐름

1. MCP 클라이언트(Claude Code, Claude Desktop, Cursor 등)가 stdio를 통해 bun run src/index.ts를 실행합니다.

2. 시작 시 서버는 data/hey-cookies.json을 검증합니다. 누락되었거나 만료된 경우 auth/hey-auth.py를 실행하여 시스템 웹뷰에서 Hey를 열고 새 쿠키를 작성합니다.

3. 도구 호출은 브라우저와 동일한 헤더를 사용하여 Hey.com에 직접 요청을 보냅니다. 응답은 파싱(node-html-parser를 통한 HTML 파싱)되어 SQLite에 캐시됩니다.

4. 쓰기 작업은 제출 전 새로운 CSRF 토큰을 가져옵니다.

프로젝트 구조

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

사용 가능한 도구

기능별로 그룹화된 33개의 도구입니다. 매개변수, 반환 형태 및 오류 동작은 docs/TOOLS.md를 참조하세요.

개인정보 보호 및 보안

• 자격 증명은 절대 저장되지 않으며, 600 권한으로 작성된 세션 쿠키만 저장됩니다.

• 인증은 전적으로 Hey의 자체 로그인 페이지(시스템 웹뷰) 내에서 이루어집니다.

• 모든 데이터는 사용자 기기에 머무릅니다. 이 프로젝트는 어떠한 원격 측정 데이터도 전송하지 않습니다.

• MCP는 stdio 전송을 사용하므로 서버가 네트워크 리스너를 열지 않습니다.

• 세션 유효성은 시작 시 및 민감한 작업 전에 확인됩니다.

취약점 보고 방법은 SECURITY.md를 참조하세요.

제한 사항

• 프롬프트 주입 위험: 많은 MCP 서버와 마찬가지로 이 서버도 치명적인 3요소의 대상이 될 수 있습니다. 받은 편지함에 도착한 악의적인 이메일이 Claude에게 다른 메시지를 유출하도록 지시할 수 있습니다. 도구 인터페이스를 적절히 다루고 위험한 작업은 승인하기 전에 검토하세요.

• 비공식 API: Hey.com의 프론트엔드는 예고 없이 변경되어 기능을 중단시킬 수 있습니다. 간헐적인 중단을 예상하고 알려진 변경 사항은 docs/API.md를 확인하세요.

• 실시간 알림 없음: 폴링 방식만 지원합니다.

• 첨부 파일 업로드는 아직 지원되지 않습니다.

• MCP 서버 인스턴스당 단일 계정만 지원합니다.

• 계정 위험: 공격적이거나 비정상적인 액세스 패턴은 이론적으로 Hey의 악용 방지 시스템을 트리거할 수 있습니다. 서버는 x-ratelimit 헤더를 준수하고 지수적으로 재시도하지만, 보장할 수는 없습니다.

• 영어 UI 전용: 서버는 Hey.com의 HTML 응답을 파싱하며 영어 문자열(예: "You ignored this thread", 라벨 이름, 버튼 텍스트)과 일치시킵니다. Hey.com이 영어가 아닌 로케일로 설정된 경우 올바르게 작동하지 않습니다.

문제 해결

• 인증 웹뷰가 열리지 않음 — Python 3.10+가 PATH에 있는지, uv pip install -r auth/requirements.txt가 성공했는지 확인하세요. Linux에서는 웹뷰 백엔드를 사용할 수 있는지 확인하세요 (python -c "import webview" 실행 시 오류가 없어야 함).

• 수주 사용 후 401/403 응답 — Hey 세션이 만료되었습니다. data/hey-cookies.json을 삭제하고 bun run dev를 다시 실행하여 재인증하세요.

• 속도 제한 (429) — 클라이언트는 x-ratelimit 헤더를 준수하고 재시도합니다. 지속적으로 429 오류가 발생하면 동시 도구 사용을 줄이거나 몇 분 기다리세요.

• MCP 클라이언트가 서버를 실행할 수 없음 — args는 상대 경로가 아닌 절대 경로여야 합니다. bun 자체가 spawn bun ENOENT 오류를 발생시키면 macOS: bun PATH를 참조하세요.

• 쿠키 이름 변경 — Hey는 이전에 세션 쿠키 이름을 변경한 적이 있습니다(예: _hey_session → session_token, docs/API.md 변경 로그 참조). Hey 업데이트 후 인증이 조용히 실패하면 새 쿠키를 캡처하여 비교하세요.

기여

풀 리퀘스트를 통한 기여를 환영합니다. 다음 사항을 준수해 주세요:

• Conventional Commits(feat, fix, docs, refactor, test, perf, cicd, revert, WIP)를 사용하세요.

• 푸시하기 전에 bun run format 및 bun run lint를 실행하세요 (Biome 기반).

• bun test가 통과하는지 확인하세요.

• Hey.com API 동작을 발견하거나 변경한 경우 docs/API.md를 업데이트하세요.

전체 개발 워크플로우는 CLAUDE.md를 참조하세요.

라이선스

MIT 라이선스 — LICENCE를 참조하세요.