email-mcp

클래식 Outlook on Windows를 통한 이메일 + 캘린더, 네이티브 COM(pywin32)으로 구동됩니다. 단일 email 명령으로 제공되며, CLI이자 stdio MCP 서버입니다. Azure 앱 등록, OAuth, PowerShell 없이 — 이미 로그인된 Outlook 데스크톱 클라이언트를 그대로 사용합니다.

요구 사항

• Windows 10/11

• 클래식 Outlook 데스크톱, 계정이 하나 이상 구성되어 있어야 함

• Python 3.10+ 및 uv

"새로운" Outlook for Windows는 COM을 노출하지 않습니다. 새 Outlook을 사용 중이고 클래식으로 전환할 수 없다면 이 도구는 작동하지 않습니다.

COM은 Outlook 데스크톱 클라이언트를 통해서만 접근됩니다 — 별도의 인증은 없습니다. Outlook에 로그인된 계정이 곧 도구가 보는 계정이며, 보낸 메일은 직접 손으로 보낸 것과 똑같이 실제 보낸 편지함 폴더에 저장됩니다.

Related MCP server: outlook-mcp

설치 / 실행

uvx로 GitHub에서 바로 실행합니다 (클론이나 수동 설치 불필요):

uvx --from git+https://github.com/kerodkibatu/email-mcp email --help

uv는 첫 실행 시 패키지를 해석하고 캐시합니다. 이후 호출은 빠릅니다.

CLI

모든 도구는 email의 하위 명령입니다. 출력은 stdout에 JSON으로 나옵니다.

# List configured Outlook accounts
uvx --from git+https://github.com/kerodkibatu/email-mcp email list-accounts

# Query across all mail folders with a MongoDB-style filter (JSON string)
uvx --from git+https://github.com/kerodkibatu/email-mcp email query \
  --filter '{"$and":[{"from":{"$contains":"@kyros.com"}},{"unread":true}]}' \
  --limit 20 --order-by received_desc

# Read one email by EntryID
uvx --from git+https://github.com/kerodkibatu/email-mcp email read --entry-id "0000000..."

# Send a new mail (account is REQUIRED — see below)
uvx --from git+https://github.com/kerodkibatu/email-mcp email send \
  --to client@example.com \
  --subject "Status update" \
  --body "Heads up — ..." \
  --account kerod@towlydigital.com

# Save a new mail as a draft instead of sending (same flags as send, no --send-as)
uvx --from git+https://github.com/kerodkibatu/email-mcp email draft \
  --to client@example.com \
  --subject "Status update" \
  --body "Heads up — ..." \
  --account kerod@towlydigital.com

MCP

email mcp는 11개의 모든 도구를 노출하는 stdio MCP 서버를 시작합니다. .mcp.json(또는 claude_desktop_config.json)에 추가하세요:

{
  "mcpServers": {
    "email": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kerodkibatu/email-mcp", "email", "mcp"]
    }
  }
}

첫 실행은 uv가 패키지를 해석하는 동안 느립니다. 이후 실행은 캐시를 사용합니다.

도구

보내는 계정 선택

send_email, reply_email, forward_email은 필수 account 매개변수를 요구합니다 — 구성된 Outlook 계정 이름의 부분 문자열(일반적으로 SMTP 주소)입니다. 이는 의도적입니다: 여러 계정(예: 개인 + 업무)이 구성된 경우 Outlook의 기본 계정으로 보내는 것은 실수로 이어질 수 있습니다 — 개인 메일이 업무 계정에서 나가거나 그 반대가 될 수 있습니다. 호출자가 계정을 명시하도록 강제하면 보내기가 명확해집니다.

제공된 account가 구성된 계정과 일치하지 않으면(대소문자 구분 없는 부분 문자열) 도구는 오류를 반환하고 사용 가능한 계정을 나열합니다. 이름을 모르면 먼저 list_accounts를 실행하세요. 전송 계정은 SendUsingAccount를 통해 Outlook 항목에 직접 설정됩니다.

{
  "to": "client@example.com",
  "subject": "Status update",
  "body": "Heads up — ...",
  "account": "kerod@towlydigital.com"
}

다른 사람으로 보내기 (실험적 — Exchange "다른 사람으로 보내기" 권한 필요)

실험적. 이 기능은 pywin32 COM을 통해서만 클래식 Outlook을 구동합니다 — Azure/OAuth 경로는 없습니다. 동작은 테넌트 정책에 따라 달라지며, 반송되거나 자동으로 "대신 보내기"로 다운그레이드되거나 보낼 편지함에 남을 수 있습니다. 최선의 노력으로 간주하세요.

send_email, reply_email, forward_email은 선택적 send_as 매개변수를 허용합니다 — 보내는 사람으로 표시할 SMTP 주소입니다. 수신자는 해당 주소를 보낸 사람으로 보게 되며, "대신 보내기" 표시는 없습니다. 이는 진정한 Exchange 다른 사람으로 보내기이며, 대신 보내기와는 다릅니다.

메커니즘적으로, 도구는 SendUsingAccount를 제공한 account(전송 사서함)로 설정한 다음, send_as를 Exchange에서 확인하고 항목의 PropertyAccessor를 통해 PR_SENT_REPRESENTING_* 및 PR_SENDER_* MAPI 속성을 모두 해당 주소로 덮어쓴 후 제출합니다. 보낸 사람 속성(대표 속성뿐만 아니라)을 덮어쓰는 것이 "대신 보내기"를 순수한 다른 사람으로 보내기로 바꾸는 핵심입니다. Exchange는 제출 시 권한을 검증합니다.

요구 사항:

• account 사용자는 send_as 사서함에 대해 다른 사람으로 보내기 권한이 있어야 하며, Exchange 관리자가 서버 측에서 부여해야 합니다. 도구는 이 권한을 부여하거나 확인할 수 없습니다 — 보내기 시도만 가능합니다.

• send_as 주소는 Exchange에서 확인 가능해야 합니다 — 일반적으로 동일한 테넌트의 사서함입니다. 외부 주소(gmail.com 등)는 확인 시 오류로 실패합니다.

• 권한이 없는 경우 동작은 테넌트 정책에 따라 달라집니다: Exchange는 메시지를 반송하거나, 자동으로 "대신 보내기"로 다운그레이드하거나, 보낼 편지함에 남길 수 있습니다.

• 이 기능은 명시적으로 승인한 Exchange 조직 내에서만 작동합니다. 외부 발신자를 사칭하는 데 사용할 수 없습니다.

{
  "to": "client@example.com",
  "subject": "Status update",
  "body": "Heads up — ...",
  "account": "admin@custom.com",
  "send_as": "contact@custom.com"
}

응답에는 send_as가 사용된 경우 해당 주소를 반영하는 sent_as 필드가 포함됩니다.

첨부 파일 보내기

send_email은 선택적 attachments 배열(절대 파일 경로)을 허용합니다. 각 경로는 존재하고 일반 파일을 가리켜야 합니다. 경로가 유효하지 않으면 도구는 오류를 반환하고 위반 항목을 나열하며 보내지 않습니다. Windows에서는 슬래시와 백슬래시 모두 허용됩니다. ~ 및 환경 변수는 확장되지 않습니다 — 완전히 해석된 경로를 전달하세요.

{
  "to": "kerod@example.com",
  "subject": "Signed contract",
  "body": "See attached.",
  "account": "kerod@towlydigital.com",
  "attachments": [
    "C:\\Users\\Kerod\\Desktop\\contract.pdf",
    "C:/Users/Kerod/Desktop/cover-letter.pdf"
  ]
}

첨부 파일 다운로드

download_attachments 도구는 이메일에서 파일을 추출하여 로컬에 저장하고 절대 폴더 경로를 반환합니다.

• 위치: 파일은 사용자의 다운로드 폴더 아래에 저장됩니다: ~/Downloads/email-attachments/YYYY-MM-DD_sender-slug_subject-slug/.

• 인라인 이미지: 로고 및 서명 이미지는 기본적으로 필터링되어 지저분함을 방지합니다. 특별히 필요하면 include_inline: true를 설정하세요.

• 멱등성: 동일한 이메일에 도구를 다시 실행하면 폴더를 안전하게 재사용하며(.entry_id 마커로 추적), 두 개의 다른 이메일이 같은 이름으로 슬러그화될 때 구분합니다.

작동 방식

email 명령은 COM을 통해 실행 중인 Outlook 인스턴스에 연결하고(실행 중인 것이 없으면 하나를 시작하는 폴백), MAPI 네임스페이스를 구동하여 메일을 읽고 씁니다. 모든 COM 접근은 단일 Outlook 세션을 통해 이루어지며, 도구는 PowerShell을 생성하지 않습니다.

즉:

• Outlook이 설치되어 있어야 합니다 (열려 있을 필요는 없음 — 첫 호출 시 시작됨)

• Outlook에 로그인된 계정이 곧 도구가 보는 계정 — 별도 인증 없음

• 보낸 메일은 사용자가 수동으로 보낸 것과 똑같이 사용자의 보낸 편지함 폴더에 나타납니다

라이선스

MIT — LICENSE 참조.