Mail Notification MCP

SMTP를 통해 프로젝트 진행 상황 및 수동 승인 이메일을 전송하는 MCP Server입니다. 표준 stdio transport를 사용하므로 Codex, Claude Desktop, Cursor, VS Code 등 MCP 클라이언트에서 호출하기에 적합합니다.

제공하는 도구

• send_progress_update: 프로젝트 진행 상황, 완료 또는 차단 보고를 전송합니다.

• request_human_approval: 수동 승인/거부가 필요한 항목을 전송하고 승인 번호를 생성합니다.

• send_simple_email: 일반 텍스트 또는 HTML 형식의 이메일을 전송합니다.

• send_custom_email: CC/BCC 및 첨부 파일을 포함한 사용자 지정 이메일을 전송합니다.

• test_smtp_connection: SMTP 연결 및 인증을 테스트합니다.

• test_imap_connection: IMAP 연결 및 인증을 테스트합니다.

• read_replies: 받은 편지함의 최신 답장을 읽습니다. 기본적으로 읽음으로 표시하지 않습니다.

• check_approval_status: 승인 번호 기준으로 기기, 구동 또는 대기 상태를 확인합니다.

• wait_for_approval: 승인, 거부 또는 타임아웃이 될 때까지 수동 답장을 폴링하며 기다립니다.

진행 보고 도구의 기본 수신자는 config.json에서 가져옵니다. 승인 이메일은 '구동' 또는 '거부'로 명시적으로 회신을 요청합니다. 다른 프로젝트는 MCP 도구를 호출하기만 하면 되고, 자체적으로 SMTP를 구현할 필요가 없습니다.

Related MCP server: mcp-email-server

1. SMTP 및 대상 사서함 설정

프로젝트 루트의 config.json을 편집합니다(템플릿은 config.example.json 참조):

{
  "smtp": {
    "host": "smtp.gmail.com",
    "port": 587,
    "secure": false,
    "username": "你的发件邮箱@gmail.com",
    "password": "",
    "password_env": "MAIL_SMTP_PASSWORD",
    "from_email": "你的发件邮箱@gmail.com"
  },
  "imap": {
    "host": "imap.gmail.com",
    "port": 993,
    "secure": true,
    "username": "你的发件邮箱@gmail.com",
    "password": "",
    "password_env": "MAIL_SMTP_PASSWORD"
  },
  "notification": {
    "to": "目标收件邮箱@example.com",
    "subject_prefix": "[工程通知]",
    "project_name": "我的工程"
  }
}

비밀번호를 파일에 직접 적기보다는 환경 변수에 저장하는 것을 권장합니다:

$env:MAIL_SMTP_PASSWORD = "你的邮箱应用专用密码"

SMTP.password에 직접 입력할 수도 있습니다. config.json은 .gitignore에 포함되어 있으므로 버전 저장소에 커밋하면 안 됩니다.

일반적인 SMTP 설정:

Gmail, QQ 등은 일반적으로 SMTP를 활성화하고 앱 전용 비밀번호(app password)를 사용해야 합니다. 웹 로그인 비밀번호를 직접 사용할 수 없는 경우, 이메일 제공업체에 요구사항에 따라 인증 번호/앱 비밀번호를 생성하세요.

IMAP은 답장을 읽는 데 사용됩니다. QQ 메일은 일반적으로 imap.qq.com:993 + SSL을 사용합니다. imap.password를 생략하면 SMTP 저장비밀번호/인증 번호를 재사용합니다. 환경 변수는 config.json을 재정의하며, IMAP_HOST, IMAP_PORT, IMAP_SECURE, IMAP_USER, IMAP_PASS, NOTIFY_TO도 사용할 수 있습니다.

2. 설치 및 테스트

Python 3.11+ 및 uv 가 필요합니다. PowerShell에서 실행하세요:

cd C:\AI_Tools\Mail
uv sync --extra dev
uv run pytest
uv run python -m email_mcp_server.server

MCP의 stdio 모드에서는 수동으로 원하지 않는 것은 입력하면 안 됩니다. MCP 클라이언트가 직접 실행해야 합니다. 먼저 test_smtp_connection과 test_imap_connection을 호출하는 것을 권장합니다.

3. 다른 프로젝트에 연동

mcpServers 형식을 지원하는 클라이언트를 기준으로, 다음 서버 항목을 클라이언트 구성에 병합하세요. Windows 경로는 must use must use must use only double backslashes:

{
  "mcpServers": {
    "mail-notification": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\AI_Tools\\Mail",
        "run",
        "python",
        "-m",
        "email_mcp_server.server"
      ]
    }
  }
}

uv가 클라이언트의 PATH에 없으면 command를 uv.exe의 절대 경로로 대체하세요. MCP 구성을 변경한 후에는 클라이언트를 다시 시작하세요.

호출 예시

진행 상황 보고:

调用 send_progress_update：
project="订单系统"
status="进行中"
summary="已完成数据库迁移脚本，并通过本地测试"
details="迁移了 12 张表，新增回滚检查"
next_steps="部署到测试环境并等待接口联调"

수동 승인:

调用 request_human_approval：
project="订单系统"
title="是否允许部署到生产环境"
request="请批准今晚 22:00 执行生产部署"
reason="测试环境已通过，预计需要 15 分钟，期间会短暂重启服务"
options="批准部署 / 延后到明天"
deadline="今天 21:30 前"

이 도구는 단일 수신자를 일시적으로 재정의할 수 있도록 선택적 to 파라미터를 지원합니다. 생략하면 config.json의 notification.to를 사용합니다.

답장 읽기:

调用 read_replies：
from_address="target@example.com"
subject_contains="Mail Notification MCP 测试邮件"
since_hours=72

승인 확인:

调用 check_approval_status：
approval_id="APR-ABC1234567"

승인 도구가 반환하는 상태는 approved, rejected, pending 또는 timeout입니다. 기본적으로 INBOX만 읽으며, 이메일의 읽음 상태를 자동으로 변경하지 않습니다.

보안 참고 사항

• 앱 전용 비밀번호 또는 인증 코드를 우선 사용하고, 메인 이메일 비밀번호는 사용하지 마세요.

• 실제 비밀번호나 실제 대상 데이터, 이메일 구성을 Git에 커밋하지 마세요.

• 기본은 로컬 stdio 사용이며, HTTP 모드는 127.0.0.1에만 바인딩됩니다.