mcp-hey

Claude가 리버스 엔지니어링된 웹 API를 통해 Hey.com 받은 편지함에 읽기/쓰기 권한을 가질 수 있도록 하는 로컬 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에서 이메일 읽기

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

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

• 메일 정리 (Set aside, Reply later, Screen in/out, Bubble up)

• 반복적인 읽기 및 전체 텍스트 검색 속도를 높이기 위한 로컬 SQLite 캐시

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

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

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

설정

사전 요구 사항

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

3. 첫 실행 — 인증

   bun run dev

   Python 인증 도우미가 Hey.com을 가리키는 시스템 웹뷰를 엽니다. 평소처럼 로그인하면 도우미가 세션 쿠키를 data/hey-cookies.json (권한 600으로 잠김)에 캡처하고 종료합니다. 이후 실행 시에는 세션이 만료될 때까지 저장된 세션을 재사용합니다.

MCP 클라이언트 설정

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를 재시작하세요.

아키텍처

데이터 흐름

1. MCP 클라이언트(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
    __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)

사용 가능한 도구

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

개인정보 보호 및 보안

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

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

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

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

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

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

제한 사항

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

• 비공식 API: Hey.com의 프론트엔드는 예고 없이 변경되어 문제가 발생할 수 있습니다. 간헐적인 중단을 예상하고 알려진 변경 사항은 docs/API.md를 확인하십시오.

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

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

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

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

문제 해결

• 인증 웹뷰가 열리지 않음 — Python 3.10+가 PATH에 있는지, 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 오류가 발생하면 동시 도구 사용을 줄이거나 몇 분 기다리세요.

• Claude Desktop/Cursor에서 Bun이 스크립트를 찾을 수 없음 — args 경로는 상대 경로가 아닌 절대 경로여야 하며, 클라이언트 실행 환경에서 bun을 찾을 수 있어야 합니다 (macOS의 경우 /opt/homebrew/bin/bun과 같은 전체 경로를 사용해야 할 수 있음).

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

기여

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

• 커밋 컨벤션 사용 (feat, fix, docs, refactor, test, perf, cicd, revert, WIP).

• 푸시 전 bun run format 및 bun run lint 실행.

• bun test 통과 확인.

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

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

라이선스

MIT 라이선스 — LICENCE 참조.