MCP 메일 서버

언어: English | 中文

Claude, Cursor 및 기타 AI 어시스턴트와 함께 사용하는 IMAP/SMTP 이메일 작업용 Model Context Protocol 서버입니다.

기능

• IMAP 작업: 여러 사서함에서 이메일 검색, 읽기 및 관리

• SMTP 지원: HTML/텍스트 콘텐츠와 첨부 파일이 포함된 이메일 전송

• 첨부 파일 관리: 첨부 파일 메타데이터 확인 및 로컬 파일로 저장

• 보안 구성: TLS/SSL을 지원하는 환경 변수 기반 설정

• AI 친화적: 이메일 작업을 위한 자연어 명령

• 자동 연결 관리: 자동 IMAP/SMTP 연결 처리

• 다중 사서함 지원: 받은 편지함, 보낸 편지함 및 사용자 지정 폴더 접근

변경 로그

[1.2.1] - 2026-03-18

수정됨

• 검색 조건(FROM/TO/SUBJECT/BODY/KEYWORD/SINCE)이 중첩 배열 형식을 사용하지 않아 TO 및 기타 검색에서 오류가 발생하던 문제 수정

• search()가 조건을 추가 배열로 감싸 복합 검색 조건을 깨뜨리던 문제 수정

• 사서함이 읽기 전용 모드로 열렸을 때 deleteMessage()가 조용히 실패하던 문제 수정

• getRecentMessages()가 IMAP RECENT 플래그를 잘못 사용하던 문제 수정; 이제 UID 기준으로 최신 N개 메시지를 가져옴

• getRecentMessages() / getUnseenMessages()가 이전 작업의 남은 사서함 상태에 의존하던 문제 수정

• cleanReplySubject()가 Re: 접두사 한 겹만 제거하여 답장 안 함 감지에서 오탐(false negative)이 발생하던 문제 수정

• 이메일 날짜가 로케일 문자열로 저장되어 플랫폼 간 new Date() 파싱이 일관되지 않던 문제 수정; ISO 8601로 변경

• ensureIMAPConnection()이 동시 초기화를 기다리는 동안 타임아웃이 없던 문제 수정

• saveSentMessage()가 저장 실패 시에도 항상 sentFolderSaved: true를 반환하던 문제 수정

• handleGetMessages() / handleDeleteMessage()가 currentBox 상태에 의존하여 메시지를 찾던 문제 수정

• text가 비어 있을 때 reply_to_email이 본문에 리터럴 "undefined"를 쓰던 문제 수정

추가됨

• 모든 검색 도구가 INBOX로만 검색을 제한하는 inboxOnly 매개변수를 지원

개선됨

• ensureSMTPConnection()에 IMAP과 동일하게 30초 타임아웃의 동시성 가드 추가

• 보낸 편지함이 RFC 6154 \Sent 특수 사용 속성을 통해 자동 감지되고 결과가 캐시되어 모든 메일 제공업체와 호환

• saveMessageToFolder() 단순화; 보낸 편지함 폴더가 없으면 저장 건너뜀

• 검색이 slice(-limit)를 사용하여 최신 메시지를 먼저 가져와 날짜 필터링 후 빈 결과가 발생하지 않도록 수정

• XSS 주입을 방지하기 위해 답장 이메일의 인용 콘텐츠에 HTML 이스케이프 적용

전체 버전 기록은 CHANGELOG.md를 참조하세요.

빠른 시작

1. 설치: npm install -g mcp-mail-server

2. 환경 변수 구성 (구성 참조)

3. MCP 클라이언트 구성에 추가

4. 자연어 사용: "오늘 받은 읽지 않은 이메일을 보여줘"

설치

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

Cursor MCP 설정에 추가:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

claude mcp add 명령으로 추가:

claude mcp add mcp-mail-server \
  -e IMAP_HOST=your-imap-server.com \
  -e IMAP_PORT=993 \
  -e IMAP_SECURE=true \
  -e SMTP_HOST=your-smtp-server.com \
  -e SMTP_PORT=465 \
  -e SMTP_SECURE=true \
  -e EMAIL_USER=your-email@domain.com \
  -e EMAIL_PASS=your-password \
  -- npx -y mcp-mail-server

또는 .claude/settings.json에 수동으로 추가:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

프로젝트 루트의 codex.json에 추가:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

다른 MCP 클라이언트도 유사하게 구성할 수 있습니다. 핵심 구성은 다음과 같습니다:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

적절한 구성 파일 위치는 각 클라이언트의 문서를 참조하세요.

사용 가능한 도구

연결 관리

• connect_all: 매개변수 불필요

• get_connection_status: 매개변수 불필요

• disconnect_all: 매개변수 불필요

사서함 작업

• open_mailbox: mailboxName (문자열, 기본값: "INBOX"), readOnly (불리언)

• list_mailboxes: 매개변수 불필요

검색 작업

• search_by_sender: sender (문자열, 이메일 주소), startDate (문자열, 선택), endDate (문자열, 선택)

• search_by_subject: subject (문자열, 키워드), startDate (문자열, 선택), endDate (문자열, 선택)

• search_by_recipient: recipient (문자열, 이메일 주소), startDate (문자열, 선택), endDate (문자열, 선택)

• search_by_body: text (문자열, 검색 텍스트), startDate (문자열, 선택), endDate (문자열, 선택)

• search_since_date: date (문자열, 날짜 형식)

• search_unread_from_sender: sender (문자열, 이메일 주소), startDate (문자열, 선택), endDate (문자열, 선택)

• search_unreplied_from_sender: sender (문자열, 이메일 주소), startDate (문자열, 선택), endDate (문자열, 선택), limit (숫자, 선택)

• search_with_keyword: keyword (문자열, 키워드), startDate (문자열, 선택), endDate (문자열, 선택)

• search_all_messages: startDate (문자열, 선택), endDate (문자열, 선택), limit (숫자, 선택, 기본값: 50)

메시지 작업

• get_message_count: 매개변수 불필요

• get_unseen_messages: 매개변수 불필요

• get_recent_messages: 매개변수 불필요

• get_message: uid (숫자), markSeen (불리언, 선택)

• get_messages: uids (배열), markSeen (불리언, 선택)

• delete_message: uid (숫자)

이메일 전송

• send_email: to (문자열), subject (문자열), text (문자열, 선택), html (문자열, 선택), cc (문자열, 선택), bcc (문자열, 선택), attachments (문자열[], 선택, 절대 파일 경로)

• reply_to_email: originalUid (숫자), text (문자열), html (문자열, 선택), replyToAll (불리언, 선택), includeOriginal (불리언, 선택)

첨부 파일 작업

• get_attachments: uid (숫자) — 메타데이터 반환: filename, contentType, size, index

• save_attachment: uid (숫자), savePath (문자열, 절대 경로), attachmentIndex (숫자, 선택, 0부터 시작), returnBase64 (불리언, 선택, 기본값: false)

사용 예시

AI 어시스턴트와 함께 자연어 명령을 사용하세요:

기본 작업

• "내 이메일 서버에 연결해줘"

• "읽지 않은 모든 이메일을 보여줘"

• "boss@company.com에서 온 이메일을 검색해줘"

• "회의에 대해 team@company.com에게 이메일을 보내줘"

• "UID 123 이메일에 답장해줘"

고급 검색

• "지난주에 제목에 'urgent'가 있는 이메일을 찾아줘"

• "boss@company.com에서 온 답장하지 않은 이메일을 보여줘"

• "team@company.com에게 보낸 이메일을 검색해줘"

• "Sales 폴더에서 모든 이메일을 가져와줘"

• "boss@company.com에서 온 읽지 않은 이메일을 보여줘"

• "지난 7일 동안의 모든 이메일을 보여줘"

• "모든 메시지를 나열해줘, 20개로 제한"

이메일 관리

• "UID 123 이메일을 삭제해줘"

• "최근 이메일을 읽음으로 표시해줘"

• "내 모든 이메일 폴더를 나열해줘"

첨부 파일 작업

• "UID 456 이메일의 첨부 파일을 보여줘"

• "UID 456 이메일의 모든 첨부 파일을 D:/Downloads에 저장해줘"

• "UID 789 이메일의 첫 번째 첨부 파일을 다운로드해줘"

• "첨부 파일 D:/report.pdf와 함께 team@company.com에게 이메일을 보내줘"

구성

환경 변수

⚠️ 모든 변수는 필수입니다

선택 변수

전송 모드 (stdio / HTTP)

기본적으로 서버는 stdio를 통해 실행됩니다(로컬 클라이언트용 표준 MCP 전송 방식). 선택적으로 HTTPS를 지원하는 Streamable HTTP 서버로도 실행할 수 있습니다.

인증서와 키가 발견되면 서버는 HTTPS로 실행되고, 그렇지 않으면 경고와 함께 일반 텍스트 HTTP로 전환됩니다.

mkcert로 로컬에서 신뢰할 수 있는 인증서를 생성하세요:

mkcert -install   # one-time: install the local CA
mkcert -cert-file certs/localhost-cert.pem -key-file certs/localhost-key.pem localhost 127.0.0.1 ::1

HTTP 모드로 실행:

MCP_TRANSPORT=http MCP_HTTP_PORT=8443 npm start
# → MCP endpoint:  https://localhost:8443/mcp
# → Health check:  https://localhost:8443/health

MCP 엔드포인트는 /mcp에서 제공되며, Streamable HTTP 사양에 따라 mcp-session-id 헤더를 통한 세션 관리와 SSE 스트리밍을 지원합니다.

일반 이메일 제공업체

IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_SECURE=true
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password

참고: 일반 비밀번호 대신 앱 비밀번호를 사용하세요.

IMAP_HOST=outlook.office365.com
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST=smtp.office365.com
SMTP_PORT=587
SMTP_SECURE=true
EMAIL_USER=your-email@outlook.com
EMAIL_PASS=your-password

보안 참고 사항

• 앱 비밀번호 사용: 가능한 경우 2FA를 활성화하고 앱 전용 비밀번호를 사용하세요.

• TLS/SSL 필수: 항상 보안 연결을 사용하세요 (IMAP_SECURE=true, SMTP_SECURE=true)

• 환경 변수: 설정 파일에 자격 증명을 하드코딩하지 마세요.

개발

1. 저장소 클론:

   git clone https://github.com/yunfeizhu/mcp-mail-server.git
   cd mcp-mail-server

2. 의존성 설치:

   npm install

3. 프로젝트 빌드:

   npm run build

4. 환경 변수 설정:

   export IMAP_HOST=your-imap-server.com
   export IMAP_PORT=993
   export IMAP_SECURE=true
   export SMTP_HOST=your-smtp-server.com
   export SMTP_PORT=465
   export SMTP_SECURE=true
   export EMAIL_USER=your-email@domain.com
   export EMAIL_PASS=your-password

5. 서버 실행:

   npm start

기여

기여는 언제나 환영합니다! 자유롭게 Pull Request를 제출해 주세요.

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하세요.

패키지 정보:

• 패키지: mcp-mail-server

• Node.js: ≥18.0.0

• 저장소: GitHub

• 이슈: 버그 신고