googlarz/proton-mail-bridge-client

Claude Desktop(또는 Cline 또는 모든 MCP client)에 귀하의 Proton Mail 받은 편지함 전체 접근 권한을 부여하세요: 읽기, 검색, 보내기, 초안 작성, 스레드 분류, 폴더 관리, 첨부 파일 저장 등 — 총 100개의 MCP 도구를 사용할 수 있습니다. 이와 동일한 기능 대부분은 스크립팅, cron 및 파이프라인 자동화를 위한 전체 CLI로도 사용 가능합니다 — Claude가 필요하지 않습니다.

Proton Drive도 사용하나요? proton-drive-mcp를 확인하세요. 이는 Proton Drive용 동반 MCP 서버이자 CLI이며 (Claude에서 암호화된 파일을 업로드, 다운로드, 공유 및 관리합니다). 이 둘을 나란히 실행하여 메일과 파일 처리를 하나의 대화로 처리할 수 있습니다. 예를 들어 여기서 첨부 파일을 저장한 다음 Drive에 업로드하는 식입니다. 관련 프로젝트(Related projects)에서 더 많은 정보를 얻으세요.

대규모 환경에서 검증됨 (v2.0.0): 57,000개 이상의 메시지가 있는 62개의 폴더/레이블에 걸친 실제 계정을 대상으로 엔드투엔드로 백필(backfill)된 전체 메일함이 검증되었습니다 — 재시작, 일시적인 IMAP 연결 끊김 및 연결 시간 초과에도 데이터 손실 없이 UID-window 단위로 처음부터 22,800개 메시지 아카이브 폴더가 백필되었습니다.

빠른 시작 (2분)

터미널이 없나요? 대신 단계별 가이드를 따르세요.

1. **Proton Mail Bridge**에 설치하고 로그인한 후, 실행 상태로 유지하세요. Bridge 앱에서 계정을 열고 Bridge 비밀번호를 복사하세요 (이것은 Proton 비밀번호가 아닙니다).
2. Claude Desktop 연결: 어떤 방법을 사용하든 상관없습니다 (종료 시 설정 덮어쓰는 것을 방지하기 위해 Claude Desktop을 완전히 종료한 후 진행하세요):
   • 번들(Bundle): (Node.js 24 이상이 필요한 장치에서) 최신 릴리스에서 proton-mail-bridge-client-<사용자 OS>.mcpb를 macOS(darwin-arm64 Apple silicon, darwin-x64 Intel), Linux(linux-x64, linux-arm64) 또는 Windows(win32-x64)용으로 다운로드하여 열어주세요. Claude Desktop이 Proton 주소와 Bridge 비밀번호, 그리고 선택적 설정(Bridge IMAP/SMTP 호스트 및 포트, 읽기 전용 여부, 전송 허용 여부, 서명, 추가 계정, 데이터 및 다운로드 폴더, 도구 티어)를 요청합니다. 기본값은 표준 Bridge 설치와 일치합니다.
   • npm: npm install -g proton-mail-bridge-client를 실행한 후, proton-mail-bridge-client setup-claude-desktop을 실행하세요 (Bridge 포트를 확인하고 설정을 작성합니다). 그 후에 Claude Desktop을 완전히 종료했다가 다시 시작하세요.
3. 작동 여부 확인: proton-mail-bridge-client doctor를 실행하거나, Claude에게

아래에 더 많은 레시피가 Try it에서 있습니다.

기능 요약 (What you get)

• Claude를 이용해 Proton Mail을 읽고 관리 — 분류(triage), 답장, 초안 작성, 보관, 검색, 이동, 스레드 일괄 처리 및 첨부 파일 추출
• 완벽한 CLI — 100가지 도구 각각에 대한 전용 명령(일반 tool <이름> 패스스루 포함)을 제공하며, 스크립팅 및 파이프라인 처리가 가능하고 cron 및 셸 스크립트에서 작동합니다.
• 빠른 로컬 검색 — 모든 쿼리마다 IMAP에 접속하지 않고 받은 편지함 전체를 대상으로 하는 전문 검색(full-text search)을 제공합니다.
• 안전 제어 기능 — 읽기 전용 모드, 발송 게이트(send gate), 파괴적 작업 확인(destructive-action confirmation), 작업별 허용 목록(per-action allowlist)
• 개인 정보 보호 우선 설계 (Privacy-native) — 외부의 타사 이메일 서비스가 관여하지 않으며; 메일은 사용자의 기기에 머무릅니다.

이것이 Proton Bridge와 어떻게 관련되는가. 이것은 Proton Mail Bridge 위에 구축된 레이어이며, 대체품이 아닙니다. Bridge는 Proton의 공식적이고 로컬인 IMAP/SMTP 게이트웨이이자 다른 소프트웨어에서 Proton 사서함에 접근할 수 있는 유일하게 지원되는 방법입니다. 이 프로젝트는 Bridge와 통신합니다. Bridge 자체의 --cli 모드는 Bridge 자체를 관리합니다(로그인, 계정 세부 정보 및 Bridge 비밀번호, 포트 및 기타 설정). 이것은 메일 클라이언트가 아닙니다. Proton은 터미널용 메일 클라이언트를 공개하지 않았기 때문에, Claude나 스크립트를 통해 읽고, 검색하고, 초안을 작성하고, 보내는 기능을 이 프로젝트가 추가하는 것입니다. 위에서 언급된 안전 제어 기능과 함께 말입니다. Bridge가 실행되고 로그인되어 있어야 합니다.

개인 정보 보호 모델 (Privacy model)

사용자의 이메일 이동 경로: Proton Mail → Proton Bridge (로컬) → 이 서버 (로컬) → 사용자의 AI 클라이언트.

어떠한 데이터도 타사 이메일 릴레이를 거치지 않습니다. Proton Bridge가 메일을 로컬에서 복호화하며; 이 서버는 127.0.0.1의 로컬 IMAP 연결을 통해 이를 읽습니다. AI 모델(Claude Desktop, Cline 등)은 사용자가 처리하도록 요청한 이메일 내용만 볼 수 있습니다 — 이것이 핵심 목적입니다 — 하지만 보내는 경우를 제외하고는 어떤 이메일도 기기를 벗어나지 않습니다.

Anthropic의 기본 Anthropic API를 사용하여 Claude Desktop을 사용하는 경우, 대화 내용(이메일 스니펫 포함)은 개인정보 보호정책에 따라 Anthropic으로 전송됩니다. LLM을 직접 호스팅하거나 로컬 전용 Claude 설정을 사용하는 경우, 어떠한 정보도 기기를 벗어나지 않습니다.

필수 준비물 (Prerequisites)

1. Proton Bridge — 설치되어 있고, 로그인했으며, 실행 중이어야 합니다.
다운로드: proton.me/mail/bridge

Bridge 비밀번호 vs Proton 비밀번호: Proton Bridge는 사용자의 Proton 계정 비밀번호가 아닌 별도의 로컬 비밀번호를 생성합니다. 이 비밀번호는 Bridge 앱의 Account → Copy password (또는 유사한 항목 — 정확한 명칭은 Bridge 버전에 따라 다름)에서 찾을 수 있습니다. 설정에 이 비밀번호가 필요합니다.

2. Node.js 24 이상 — 확인 방법: node --version

3. 브릿지 자격 증명 (Bridge credentials) — Bridge 앱에서 가져옵니다:

• IMAP 호스트/포트 (기본값: 127.0.0.1:1143)
• SMTP 호스트/포트 (기본값: 127.0.0.1:1025); IMAP과 SMTP 비밀번호는 동일한 Bridge 비밀번호입니다.
• 사용자 이름 (사용자의 Proton 이메일 주소)
• Bridge 비밀번호 (위 참고 사항 참조)

설치 (Install)

npm (권장):

npm install -g proton-mail-bridge-client

Homebrew:

brew tap googlarz/tap
brew install proton-mail-bridge-client

git clone https://github.com/googlarz/proton-mail-bridge-client.git
cd proton-mail-bridge-client
npm install
...

proton-mail-bridge-client 바이너리는 빌드 후 리포지토리 내에서 사용할 수 있습니다.

Claude Desktop에 연결 (Connect to Claude Desktop)

안내 설정 마법사(guided setup wizard)를 실행합니다:

proton-mail-bridge-client setup-claude-desktop

이 마법사는 다음 작업을 수행합니다:

• 로컬 Bridge 포트를 확인합니다.
• Bridge 사용자 이름과 Bridge 비밀번호를 요청합니다.
• Claude Desktop의 MCP 설정 항목을 작성합니다.

런타임은 먼저 스테이징 디렉터리에 설치된 후, 확인(Node 시작, better-sqlite3가 데이터베이스 열기, dist 가져오기, 버전 일치) 과정을 거쳐야만 교체됩니다. 이전 런타임은 <runtime dir>.previous로 옆에 남아 있으며, 설치 실패 시에는 작동 중인 파일이 손상되지 않습니다. 설정(config)은 대체되는 것이 아니라 병합됩니다: 수동으로 추가한 기존 env 키는 유지되며, 설정은 원자적으로 다시 작성됩니다 (가장 최신 5개의 .bak-* 사본이 보존됨). 비밀번호는 절대 출력되지 않습니다. 설치를 확인하려면 npm run check:claude-desktop을 실행하세요. 이 명령, 런타임 또는 데이터베이스 모듈 중 하나라도 문제가 있으면 비(非)제로 값으로 종료됩니다.

설정 완료 후: Claude Desktop을 다시 시작하고 Proton Bridge가 열려 있는지 확인한 다음, + → Connectors → proton-mail-bridge를 확인하세요.

업데이트하기

npm update -g proton-mail-bridge-client
proton-mail-bridge-client setup-claude-desktop

수동 설정(Manual config)

위자드(wizard)가 설정을 자동으로 처리합니다. 수동으로 설정해야 하는 경우, 세 가지 자격 증명 방식이 지원됩니다:

{
  "mcpServers": {
    "proton-mail-bridge": {
...

{
  "mcpServers": {
    "proton-mail-bridge": {
...

{
  "mcpServers": {
    "proton-mail-bridge": {
...

Claude 코드에 연결하기(Connect to Claude Code)

전역으로 설치한 다음, 하나의 명령어로 서버를 등록하세요:

npm install -g proton-mail-bridge-client

claude mcp add proton-mail-bridge \
...

your-bridge-password는 Bridge 앱 자체의 비밀번호(Bridge → account → Mailbox details)이며, Proton 계정 비밀번호가 아닙니다. Prerequisites 아래 참고 사항을 확인하세요.

기본적으로 이 명령어는 현재 프로젝트에 대해서만 서버를 등록합니다. 모든 프로젝트에서 사용 가능하게 하려면 -s user 플래그를 추가하세요:

claude mcp add proton-mail-bridge -s user \
  -e [email protected] \
  -e PROTONMAIL_PASSWORD=your-bridge-password \
...

연결이 되었는지 확인하세요:

claude mcp list

평문 환경 변수 대신 파일 기반 또는 명령어 기반 자격 증명을 사용하려면, 위 Manual config의 자격 증명 방법 섹션에서와 같이 -e PROTONMAIL_USERNAME_FILE=/path/to/file (또는 _COMMAND)을 추가하세요.

Cline에 연결하기 (VS Code)

전역으로 설치한 후 (npm install -g proton-mail-bridge-client), Cline의 MCP 설정에서 다음 단계를 따르세요:

• VS Code → Cline 확장 패널 → MCP 서버 아이콘 → MCP 설정 편집
• 또는 직접 수정: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (macOS)

서버 추가:

{
  "mcpServers": {
    "proton-mail-bridge": {
...

파일 기반 또는 명령어 기반 자격 증명의 경우, 위 Claude Desktop 수동 설정에서 사용된 동일한 PROTONMAIL_USERNAME_FILE / PROTONMAIL_PASSWORD_COMMAND 패턴을 사용하세요.

저장 후 Cline 확장을 다시 로드하세요. Proton Mail 도구가 Cline의 도구 목록에 나타날 것입니다.

다중 계정 지원 (v2.1.0 이상)

동일한 서버에서 여러 개의 Proton 메일함 사용하기: 하나의 계정의 여러 주소(Bridge의 Split Addresses 기능)이거나, 동일한 Bridge에 로그인된 별도의 Proton 계정을 사용할 수 있습니다. 각 계정은 자체 격리 서비스 스택, 로컬 인덱스 및 초안 저장소를 갖게 됩니다.

설정

Proton Bridge에서는 각 주소 또는 계정을 개별 로그인으로 만듭니다. Split Addresses를 활성화하면 모든 주소가 로그인을 가지며, 별도의 계정은 각각 고유한 로그인을 가집니다. Bridge는 각 로그인에 대해 별도의 비밀번호를 생성하며, 이 비밀번호는 IMAP과 SMTP 모두에서 사용 가능합니다. 첫 번째 계정은 PROTONMAIL_USERNAME / PROTONMAIL_PASSWORD이며, PROTONMAIL_ACCOUNTS_JSON에는 추가되는 주소들만 한 줄의 JSON 배열로 나열됩니다:

{
  "mcpServers": {
    "proton-mail-bridge": {
...