imap-mcp

어떤 사서함이든 두 번째 뇌(second brain)에 연결하세요.

IMAP을 통해 메일을 읽는 MCP 서버입니다 — iCloud, Gmail, Outlook, Fastmail, 대학이나 회사 메일, 프로토콜을 지원하는 모든 메일함 — 그리고 이를 검색 가능한 마크다운 노트로 변환하며, Mycelium 런타임이 직접 수집하는 RawItem 레코드도 생성합니다.

MIT 라이선스. macOS, Linux, Windows에서 실행됩니다.

왜 IMAP인가

모든 메일 제공업체는 IMAP을 지원합니다. 하나의 커넥터로 모두를 커버할 수 있으며, 이는 한 방에 서로 다른 사서함을 가진 사람들이 모여 있을 때 중요합니다.

이미 적절한 OAuth 커넥터가 있는 제공업체라면 그것을 우선 사용하세요 — Gmail은 google-workspace-mcp, Outlook은 microsoft-365-mcp. OAuth는 범위가 제한되고 철회 가능한 접근 권한을 제공하지만, IMAP 앱 비밀번호는 그렇지 않습니다. 이 서버는 이 두 커넥터가 도달할 수 없는 사서함을 위한 것입니다: Mail에 대한 OAuth 권한을 전혀 발급하지 않는 iCloud와, 그 외 모든 소규모 또는 자체 호스팅 제공업체입니다.

Related MCP server: imap-2-mcp

지원 제공업체

서버 자체에 imap_list_providers로 물어보세요 — 각 제공업체의 호스트와 비밀번호를 발급받는 정확한 페이지를 반환합니다.

설정

SETUP.md를 참조하세요. 세 단계이며, 비밀번호는 직접 발급합니다.

도구

검색+실행 표면이 효율을 내기 시작하는 ~15개 미만의 임계값 아래에 있는 8가지 작업이므로, 작업당 하나의 도구로 구성되어 있습니다.

안전

사서함은 절대 수정되지 않습니다. 세션은 EXAMINE(읽기 전용)으로 열리고 모든 fetch는 BODY.PEEK[]를 사용합니다. 일반 FETCH BODY[]는 부작용으로 \Seen 플래그를 설정하므로, "읽기 전용" 동기화가 조용히 읽지 않은 메일을 읽음으로 표시할 수 있습니다. 무언가를 쓰는 유일한 도구는 볼트에 노트를 쓰는 것뿐입니다.

비밀번호는 기기를 떠나지 않습니다. OS 키체인에 저장되며, 설정 파일에 기록되지 않고, 로그에 남지 않으며, 어떤 도구도 반환하지 않습니다. IMAP LOGIN 실패는 실패한 명령을 그대로 에코백하는데 — 여기에는 비밀번호가 포함됩니다 — 따라서 인증 오류는 통과시키지 않고 통째로 대체됩니다.

이메일은 신뢰할 수 없는 입력으로 취급됩니다. 모든 메시지 본문은 UNTRUSTED_EMAIL_BODY 펜스로 감싸지며, 자신의 펜스를 벗어나기 위해 닫는 마커를 위조하는 본문은 무력화됩니다. 메일은 요약할 데이터이지, 따라야 할 지침이 아닙니다. 이는 생각보다 중요합니다: 누구나 이메일을 보낼 수 있으므로, 펜스가 없는 본문은 낯선 사람이 어시스턴트의 컨텍스트에 직접 글을 쓰는 것과 같습니다.

아무것도 조용히 건너뛰지 않습니다. 서버가 사서함 번호를 다시 매기면 (UIDVALIDITY 변경), 동기화 커서는 폐기되고 응답에 uidvalidity_reset: true가 표시됩니다 — 오래된 커서는 그렇지 않으면 관련 없는 메시지를 가리키며 실제 메일을 영원히 건너뛸 수 있습니다. 필터링된 메시지에는 해당 메시지를 걸러낸 규칙이 포함되며, imap_explain_filter는 개별 메시지 하나를 설명합니다.

모든 쓰기는 어디로 갔는지 명시합니다. 결과에는 vault_root와 root_source가 포함되므로, 잘못된 폴더에 들어간 메일은 몇 달 후에 발견되는 것이 아니라 첫 응답에서 바로 확인할 수 있습니다.

필터

스마트 기본값이 중요한 것은 유지하고 노이즈는 제거합니다. 폴더 이름은 제공업체와 언어에 따라 다르므로 하드코딩하지 않고 제공업체 프로필에서 가져옵니다 — Gmail은 [Gmail]/ 아래에 중첩되고, Outlook은 Junk Email이라고 하며, 스페인어 로케일 계정은 Enviados라고 표시합니다.

명시적 차단은 명시적 허용보다 우선하며, 둘 다 스마트 기본값보다 우선합니다. apply_smart_filter=False로 기본값을 완전히 끌 수 있습니다.

두 소비자, 하나의 코어

imap_client.py가 IMAP을 사용하는 유일한 모듈입니다.

• 두 번째 뇌 — imap_sync_to_vault가 External Inputs/<Provider>/<mailbox>/YYYY-MM-DD-<slug>.md를 작성합니다

• Mycelium 런타임 — imap_export_for_runtime이 런타임의 RawItem과 필드 대 필드로 일치하는 레코드를 생성하므로, 서버 측 어댑터는 이를 재구현하는 대신 감싸기만 하면 됩니다

테스트

uv run pytest -q

네트워크가 필요 없는 65개의 테스트. 보안 가드(펜스 이스케이프, 경로 격리, 자격 증명 비누출)는 각각 변형 테스트(mutation test)를 거쳤습니다: 가드를 제거하고, 해당 테스트가 실패하는 것을 확인하고, 가드를 복원했습니다.

아직 검증되지 않음: 어떤 제공업체의 실제 사서함에 대한 라이브 스모크 테스트는 실행되지 않았습니다. 모든 테스트는 합성 픽스처를 사용하므로 파싱과 필터링 로직은 입증되지만, 라이브 서버가 이러한 정확한 명령을 수락한다는 것은 입증되지 않았습니다.