mail-mcp-oauth

Claude.ai용 자체 호스팅 OAuth 2.1 지원 IMAP/SMTP MCP 서버입니다. maxx3250/claude-mail-mcp의 포크로, OAuth 2.1 + Dynamic Client Registration + PKCE 계층이 내장되어 있으며, Render에서 단일 무상태(stateless) 프로세스로 실행되도록 조정되었습니다 (VPS 불필요, nginx 불필요, systemd 불필요, 영구 디스크 불필요).

멀티 계정: 하나의 배포로 여러 사서함(Gmail, 사용자 지정 도메인 등)을 지원하며, 각 사서함은 IMAP/SMTP로 접근할 수 있습니다. 모든 MCP 도구는 선택적 account 매개변수를 받아 어떤 사서함을 대상으로 작업할지 결정합니다.

업스트림과의 변경 사항

• OAuth 2.1 내장 (src/oauth.ts): /register (DCR), /authorize (PKCE + 단일 사용자 로그인 폼), /token. 별도의 OAuth shim 프로세스는 없습니다. 업스트림은 이러한 shim을 언급하지만 공개하지 않았으므로, 이 포크는 동일한 Express 앱 안에서 직접 구현합니다.

• 설계상 무상태: access/refresh 토큰은 서명된 JWT입니다(DB 없음). 등록된 OAuth 클라이언트와 진행 중인 인증 코드는 메모리에 저장됩니다. 재시작 시 Claude.ai가 자동으로 다시 등록하며, 이는 Claude.ai의 MCP 클라이언트가 이미 처리하는 동작입니다.

• 환경 변수에서 계정 읽기: Render의 파일 시스템은 일시적이므로 디스크의 파일 대신 ACCOUNTS_JSON을 사용합니다. 파일 기반 ACCOUNTS_FILE은 로컬/VPS에서 계속 사용할 수 있습니다.

• CalDAV/calendar 도구 제거 — 이 배포에는 필요하지 않으며, 의존성 표면을 줄입니다(tdav, ical.js).

Related MCP server: IMAP MCP Server

Architecture

Claude.ai (web)
    │  HTTPS + OAuth 2.1 (DCR, PKCE, JWT)
    ▼
Render (TLS terminated automatically, custom domain mcp-mail.<domain>)
    ▼
this process (single Node service)
    ├── /.well-known/oauth-authorization-server, /register, /authorize, /token   (src/oauth.ts)
    ├── /mcp  (Bearer-gated MCP Streamable HTTP transport)
    │     ├── ImapClient   ──▶ imapflow   ──▶ IMAP server (993/143) per account
    │     └── SmtpClient   ──▶ nodemailer ──▶ SMTP server (465/587) per account
    └── /health

Local setup

npm install
cp .env.example .env
# fill in PUBLIC_URL, ACCOUNTS_JSON (see docs/ACCOUNTS.md), OAUTH_USER,
# OAUTH_PASS, and JWT_SECRET (openssl rand -hex 32)
npm run dev

Render에 배포

전체 단계별 가이드는 docs/DEPLOY_RENDER.md를 참고하세요. (GitHub push, Render web service, custom domain, Netcup DNS, Claude.ai 연결).

Accounts

accounts.json 스키마와 제공자별 설정은 docs/ACCOUNTS.md를 확인하세요. (Gmail 앱 비밀번호, Netcup Webhosting IMAP/SMTP, 그리고 Hotmail/Outlook.com이 별도의 OAuth2 흐름이 필요한 이유).

Claude에 제공되는 도구

License

MIT — LICENSE 참조. Original work by Markus Stöger (maxx3250/claude-mail-mcp).