Proton Mail Bridge MCP 및 CLI

Claude Desktop을 위한 제대로 된 Proton Mail 통합.

🌉 Proton Mail Bridge MCP는 Claude Desktop 및 터미널을 위한 로컬 우선 Proton Mail 통합 도구입니다. 이 도구를 사용하면 전체 MCP 서버와 실제 CLI를 통해 Proton Bridge를 거쳐 Proton Mail을 읽고, 검색하고, 초안을 작성하고, 보내고, 동기화하고, 관리할 수 있습니다.

설정 후 Claude Desktop은 컴퓨터에 설치된 이 MCP의 안정적인 로컬 버전을 사용합니다. 단일 저장소, 단일 작업 공간 또는 단일 채팅 폴더에 국한되지 않습니다.

간단히 요약하자면:

컴퓨터에 Proton Mail Bridge MCP를 설치합니다.
Claude Desktop에 연결합니다.

사용하기 위해 MCP 내부 구조를 이해할 필요는 없습니다. Proton Bridge가 이미 컴퓨터에서 작동 중이라면 설정은 간단합니다.

60초 설정

Proton Bridge가 이미 컴퓨터에서 작동 중인 경우:

git clone https://github.com/googlarz/proton-mail-bridge-mcp.git
cd proton-mail-bridge-mcp
npm install
npm run setup:claude-desktop

그 다음:

Proton Bridge를 계속 켜둡니다.
Claude Desktop을 재시작합니다.
아무 채팅이나 열고 + -> Connectors -> proton-mail-bridge를 확인합니다.

터미널 측에서 빠른 상태 확인을 원할 경우:

npm run check:claude-desktop
proton-mail-bridge doctor --json

이 README에 표시된 npm run ... 명령어를 사용하세요.

설정 및 설치 프로그램 진입점이 빌드된 dist/ 출력물에 있고, npm 스크립트가 이미 올바른 파일을 가리키고 있기 때문에 이 명령어를 사용하는 것이 중요합니다.

사용 이유

도구를 전환할 필요 없이 Claude Desktop에서 Proton Mail을 확인하세요.
청구서, 여행 이메일, 문서 및 스레드를 더 빠르게 검색하세요.
Proton Bridge를 통해 초안 작성, 답장, 전달 및 전송을 수행하세요.
Claude Desktop이나 터미널에서 직접 동일한 백엔드를 사용하세요.
Claude Desktop 및 Proton Bridge 설정 문제를 빠르게 진단하세요.

이 프로젝트의 존재 이유

Claude에는 기본 Gmail 커넥터가 있지만, 현재 Proton Mail 커넥터는 없습니다. 이 프로젝트는 Proton 사용자를 위해 그 격차를 해소합니다.

원래의 protonmail-pro-mcp 아이디어는 매우 유망했지만, 제가 시작한 코드베이스는 그대로 사용할 수 없었습니다. 저는 이를 작동하는 MCP 서버로 재구축하고, 누락된 부분을 구현했으며, 일상적으로 유용하게 사용할 수 있도록 긴 개선 목록을 추가했습니다.

강점:

Proton Bridge를 통한 실제 Proton 지원.
읽기 및 쓰기 작업: 초안 작성, 전송, 답장, 전달, 보관, 휴지통 이동, 복원.
첨부 파일 콘텐츠 액세스 및 파일 저장.
로컬 인덱싱, 스레드 분류, 후속 조치 보기 및 백그라운드 새로 고침.
설치 후 컴퓨터 전체에서 사용할 수 있는 로컬 우선 Claude Desktop 설정.
동기화, 검색, 읽기, 진단, Claude Desktop 유지 관리 및 터미널에서의 전체 MCP 도구 실행을 위한 실제 CLI.

기대 사항:

Proton Bridge와 함께 컴퓨터에서 로컬로 실행됩니다.
Claude Desktop에 연결되지만, 공식 Claude 커넥터는 아닙니다.
소스 링크는 기본 Proton 웹메일 링크가 아닌 MCP 계층에서 제공됩니다.
설치 후 Claude Desktop은 해당 컴퓨터의 모든 채팅에서 이 도구를 사용할 수 있습니다.

신뢰 및 안전

컴퓨터에서 로컬로 실행됩니다.
컴퓨터의 Proton Bridge를 통해 Proton Mail과 통신합니다.
호스팅된 메일 릴레이나 원격 URL 서비스가 필요하지 않습니다.
더 안전한 기본값을 원할 경우 읽기 전용 모드로 실행할 수 있습니다.
구성에 원시 자격 증명을 넣고 싶지 않은 경우 *_FILE 및 *_COMMAND 비밀 값을 지원합니다.
해당 기능을 명시적으로 사용할 때만 전송 또는 사서함 변경 작업을 수행합니다.

검증된 기능

다음 경로는 실제 Proton Bridge 설정에 대해 실시간 테스트를 거쳤습니다:

IMAP 연결 및 폴더 목록
SMTP 연결 및 전송
전체 메시지 읽기
로컬 인덱싱 및 증분 동기화
스레드 보기, 요약 및 후속 조치 워크플로우
Proton 초안으로의 원격 초안 동기화
첨부 파일 목록 및 저장
CLI 명령어 및 일반 MCP 도구 호출

주요 기능

Proton Bridge IMAP 및 SMTP를 통해 Claude를 Proton Mail에 연결합니다.
폴더, 메시지 및 첨부 파일을 읽습니다.
실시간 메일 및 로컬로 인덱싱된 메일을 검색합니다.
초안을 생성, 업데이트, 동기화 및 전송합니다.
이메일 전송, 답장 및 전달을 수행합니다.
읽음/안 읽음 표시, 별표 표시/해제, 이동, 보관, 휴지통 이동, 복원 및 삭제를 수행합니다.
증분 동기화 체크포인트가 포함된 로컬 SQLite 인덱스를 구축합니다.
IMAP IDLE 인식 새로 고침으로 사서함 변경 사항을 감시합니다.
IMAP 데이터에서 정규화된 레이블과 스레드를 재구성합니다.
인라인 이미지, 캘린더 초대, 아카이브 및 서명 파일을 포함한 더 많은 첨부 파일 유형을 분류합니다.
실행 가능한 스레드 보기, 받은 편지함 요약, 후속 조치 후보, 회의 준비, 문서 찾기 보기 및 스레드 요약을 생성합니다.
배치 및 스레드 사서함 작업을 위한 더 안전한 드라이 런(dry-run) 미리보기를 지원합니다.
다운스트림 인용 스타일 렌더링을 위해 MCP 리소스 링크 및 구조화된 소스 메타데이터를 내보냅니다.

참고 사항

Proton Bridge를 사용합니다. 이유: 이 프로젝트는 Proton Bridge가 제공하는 로컬 IMAP 및 SMTP 액세스를 통해 연결됩니다.
로컬에서 실행됩니다. 이유: Proton Bridge는 일반적으로 사용자 자신의 컴퓨터에서 실행되므로, 이 MCP 서버도 로컬에서 실행되도록 설계되었습니다.
스레드와 레이블은 IMAP 데이터에서 재구성됩니다. 이유: Proton 기본 스레드 및 레이블 객체는 공식 Claude 커넥터 경로를 통해 여기에서 사용할 수 없습니다.
첨부 파일 처리는 광범위하지만 마법은 아닙니다. 이유: 캘린더 초대 및 일반적인 문서/이미지 첨부 파일을 포함한 일반적인 사례는 잘 작동하지만, 이메일 MIME 형식은 발신자와 클라이언트에 따라 여전히 복잡할 수 있습니다.

여전히 누락된 기능 및 이유

기본적으로 원격 URL 커넥터가 없습니다. 이유: 현재 제품은 사용자 컴퓨터의 Proton Bridge와 통신하며, Proton Bridge는 일반적으로 호스팅된 서비스가 아닌 로컬에서 실행됩니다.
공식 Claude 인증 흐름이나 기본 Proton 딥 링크가 없습니다. 이유: 이는 Anthropic의 플랫폼 수준 지원과 IMAP/SMTP가 제공할 수 있는 것보다 더 풍부한 Proton의 공급자 지원이 필요합니다.
진정한 Proton 기본 대화 모델이 없습니다. 이유: 이 프로젝트는 더 풍부한 Proton 전용 API를 호출하는 대신 Bridge 메일 데이터에서 스레드와 레이블을 재구성합니다.
더 나은 Proton 기본 경험은 나중에 가능할 수 있습니다. 이유: Proton이 더 나은 공개 통합 경로 또는 더 깔끔한 로컬/호스팅 브리지 스토리를 제공한다면, 이 프로젝트는 기본 Gmail 경험에 더 가까워질 수 있습니다. 저는 해당 생태계가 개선되기를 기다리고 있습니다.

시작하기 전에

다음이 필요합니다:

Claude Desktop
Node.js 18 이상
Proton 계정
설치 및 로그인된 Proton Bridge
약 10분

Proton Bridge에서 다음 정보가 필요합니다:

IMAP 호스트
IMAP 포트
SMTP 호스트
SMTP 포트
사용자 이름
Bridge 비밀번호

대부분의 로컬 Bridge 설정에서 기본값은 다음과 같습니다:

IMAP 호스트: 127.0.0.1
IMAP 포트: 1143
SMTP 호스트: 127.0.0.1
SMTP 포트: 1025

🚀 설정 개요

설정은 두 부분으로 나뉩니다:

로컬 MCP 서버 설치
Claude Desktop에 연결

일반적인 경로는 가이드 설정 마법사를 사용하는 것입니다. 수동 경로는 더 많은 제어를 원하는 사용자만을 위한 것입니다.

중요:

저장소 폴더는 MCP를 설치하거나 업데이트할 때만 필요합니다.
Claude Desktop 자체는 설정 후 안정적인 컴퓨터 전체 런타임을 사용합니다.
따라서 이는 단일 프로젝트 폴더뿐만 아니라 컴퓨터의 일반적인 Claude Desktop 사용을 위한 것입니다.

1부: 컴퓨터에 Proton Mail Bridge MCP 설치

1. 🔐 Proton Bridge 열기

Proton Bridge를 열고 계정이 연결되어 있는지 확인하세요.

Bridge에서 사서함 세부 정보 또는 "Configure email client" 보기를 열고 다음을 복사하세요:

IMAP 호스트 및 IMAP 포트
SMTP 호스트 및 SMTP 포트
사용자 이름
Bridge 비밀번호

Proton Bridge를 계속 실행하세요. 이 MCP를 사용하는 동안 닫지 마세요.

2. 📥 프로젝트 다운로드

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

원하는 경우 저장소를 복제하는 대신 최신 GitHub 릴리스에서 소스를 다운로드할 수도 있습니다.

컴퓨터에 npm이 없는 경우 먼저 Node.js 18+를 설치한 다음 명령어를 다시 실행하세요.

이 시점에서 MCP 서버 파일이 컴퓨터에 있으며 Claude Desktop 단계를 수행할 준비가 되었습니다.

저장소는 원하는 곳 어디에나 복제할 수 있습니다. 이 폴더는 설치 및 업데이트에 사용됩니다. Claude Desktop은 설정이 완료된 후 이 폴더에 묶여 있지 않습니다.

2부: Claude Desktop에 사용 지시

3. 🪄 Claude Desktop용 Proton Mail Bridge MCP 설정

npm run setup:claude-desktop

이 명령어는 Claude Desktop 앱 자체를 설치하지 않습니다.

Claude Desktop은 이미 설치되어 있어야 합니다.

이 명령어가 수행하는 작업은 다음과 같습니다:

표준 Proton Bridge 로컬 포트를 확인합니다.
Proton Bridge 사용자 이름과 Bridge 비밀번호를 묻습니다.
재정의하지 않는 한 표준 로컬 Bridge 주소를 사용합니다.
이 MCP 서버를 빌드합니다.
이 저장소 외부의 Claude Desktop을 위한 안정적인 로컬 런타임 복사본을 설치합니다.
설치된 런타임을 시작하는 방법을 Claude에게 알려주는 Claude Desktop 구성 항목을 작성합니다.
이 MCP 서버에 필요한 PROTONMAIL_* 값을 해당 로컬 Claude Desktop 구성 내에 저장합니다.
변경하기 전에 이전 Claude Desktop 구성을 백업합니다.

즉, 간단히 말해서:

이 명령어는 이 컴퓨터의 Claude Desktop을 위한 Proton Mail Bridge MCP 통합을 설치하거나 업데이트합니다.
Claude Desktop 앱 자체를 설치하지 않습니다.
실행한 폴더에 Claude를 고정하지 않습니다.

4. 🔁 Claude Desktop 재시작

마법사가 완료된 후:

Claude Desktop을 재시작합니다.
Proton Bridge를 계속 켜둡니다.
Claude Desktop에서 아무 채팅이나 엽니다.
채팅 상자 근처의 + 버튼을 클릭한 다음 Connectors를 엽니다.
proton-mail-bridge가 나타나고 도구를 사용할 수 있는지 확인합니다.
두 번째 확인을 원하면 Claude Desktop 개발자 설정을 열고 MCP 연결 상태/로그를 확인하세요.

안정적인 런타임이 설치되는 위치:

macOS: ~/Library/Application Support/Proton Mail Bridge MCP
Linux: ~/.local/share/proton-mail-bridge-mcp
Windows: %APPDATA%\Proton Mail Bridge MCP

🤖 Claude Desktop에서의 작동 방식

Claude Desktop이 이미 열려 있다면, 가장 먼저 알아야 할 사항은 다음과 같습니다:

Claude Desktop은 URL을 묻는 원격 커넥터도 지원합니다.
이 프로젝트는 그런 종류의 커넥터가 아닙니다.
Proton Bridge도 컴퓨터에서 로컬로 작동하므로 이 도구도 로컬에서 작동합니다.
따라서 여기서 올바른 설정은 원격 URL 상자가 아닌 로컬 Claude Desktop 설치 흐름입니다.

이 도구가 여전히 유용한 이유:

Gmail은 오늘날 가장 네이티브한 Claude 경험을 제공합니다.
Proton 사용자는 아직 동일한 공식 경로를 가지고 있지 않습니다.
이 프로젝트는 Claude Desktop에 실용적인 로컬 Proton 통합을 즉시 제공합니다.

붙여넣을 원격 URL이 없는 이유:

원격 URL 커넥터는 호스팅된 MCP 서버를 예상합니다.
이 프로젝트는 사용자 컴퓨터의 Proton Bridge에 도달할 것으로 예상합니다.
Proton Bridge는 일반적으로 127.0.0.1에서 로컬 IMAP/SMTP 액세스를 노출합니다.
따라서 가장 간단하고 안전한 설정은 원격이 아닌 로컬입니다.

즉, 현재 릴리스에서 지원되는 Claude Desktop 경로는 다음과 같습니다:

가이드가 있는 제로 수동 구성 흐름을 위한 npm run setup:claude-desktop
고급 또는 자동화된 Claude Desktop 설치를 위한 npm run install:claude-desktop
이 저장소를 업데이트한 후 설치된 Claude Desktop 런타임을 새로 고치기 위한 npm run update:claude-desktop
Claude Desktop이 여전히 유효한 Proton Mail Bridge MCP 런타임을 가리키고 있는지 확인하기 위한 npm run doctor:claude-desktop
CLAUDE-DESKTOP-PACKAGING.md에 문서화된 .mcpb 로컬 확장 트랙

🖥️ CLI

터미널에서 직접 Proton Mail Bridge MCP를 사용할 수도 있습니다.

이는 다음과 같은 경우에 유용합니다:

Claude Desktop을 열지 않고 Proton Bridge를 테스트할 때
더 적은 단계로 빠른 검색이나 읽기를 수행할 때
동기화 및 진단을 스크립트화할 때
Claude에게 사용을 요청하기 전에 로컬 메일 스택이 작동하는지 확인할 때
터미널에서 전체 MCP 도구 표면을 직접 호출할 때

CLI 바이너리는 다음과 같습니다:

proton-mail-bridge

또는 저장소에서:

npm run cli -- help

주요 명령어:

proton-mail-bridge status
proton-mail-bridge doctor
proton-mail-bridge sync --folder INBOX --limit 150
proton-mail-bridge search "label:inbox invoice"
proton-mail-bridge search --live --from openai.com
proton-mail-bridge read INBOX::25642
proton-mail-bridge tools
proton-mail-bridge tool get_connection_status
proton-mail-bridge tool search_indexed_emails --args '{"query":"invoice","limit":3}'
proton-mail-bridge claude check
proton-mail-bridge claude install

대부분의 명령어는 기계 판독 가능한 출력을 위해 --json을 지원합니다.

실용적인 예:

# Check whether Proton Bridge and Claude-side wiring are healthy
proton-mail-bridge doctor --json

# Search indexed mail
proton-mail-bridge search "label:inbox invoice" --limit 10

# Read one message
proton-mail-bridge read INBOX::25642

# Call any MCP tool directly from Terminal
proton-mail-bridge tools
proton-mail-bridge tool get_connection_status --json
proton-mail-bridge tool search_indexed_emails --args '{"query":"invoice","limit":3}'

# Check Claude Desktop integration
proton-mail-bridge claude check --json

CLI가 MCP 서버가 노출하는 모든 것에 도달하게 하려면 다음을 사용하세요:

proton-mail-bridge tools
proton-mail-bridge tool <tool-name> --args '{"key":"value"}'
proton-mail-bridge tool <tool-name> --args-file ./input.json

이렇게 하면 동일한 시스템을 사용하는 두 가지 방법이 제공됩니다:

Claude Desktop은 이를 MCP 서버로 사용합니다.
터미널은 일반 MCP 도구 호출을 포함하여 이를 CLI로 사용합니다.

Bridge 사용자를 위한 제로 수동 구성 경로

프로젝트 폴더에서 터미널을 엽니다.
다음을 실행합니다:

npm run setup:claude-desktop

다음 항목에 대한 프롬프트에 응답합니다

Proton Mail Bridge MCP