mail-mcp

셀프 호스팅, 제공업체에 구애받지 않는 메일 서비스입니다. 모든 사서함의 IMAP/SMTP 자격 증명을 가리키면 다음을 제공합니다:

• REST API — 일반적인 사서함 작업(폴더 목록, 메시지 목록/조회/검색, 보내기, 플래그 지정, 이동, 삭제, 할당량(최선의 노력))을 미러링합니다.

• Webhooks (message.received) — 지속적인 IMAP IDLE 감시자를 통해 새 메일이 도착할 때마다 HTTP POST를 발행하며(각 웹훅에 대한 Bearer 시크릿 포함), 수신 엔드포인트가 실패하면 지수 백오프(최대 6회 시도)로 재시도합니다.

• MCP 서버 (Streamable HTTP, POST /mcp) — 동일한 작업을 도구로 노출하므로 모든 MCP 호환 에이전트가 직접 사용할 수 있습니다.

처음부터 다중 사서함 지원: config/accounts.json에 원하는 만큼 계정을 추가하세요.

REST API의 요청 본문은 Zod (lib/schemas.js)로 검증됩니다. 잘못된 페이로드는 메일 계층에 도달하기 전에 필드 수준 오류와 함께 422 ERR_VALIDATION_FAILED를 받습니다. 웹훅 구독은 평면 JSON 파일 대신 SQLite(config/webhooks.sqlite, better-sqlite3 사용)에 저장됩니다. MAIL_MCP_MAX_MESSAGE_SIZE(기본값 25MB)보다 큰 메시지는 bodyTruncated: true와 함께 반환되며, 본문/첨부 파일이 분석되지 않아 대용량 메시지가 메모리에 로드되는 것을 방지합니다.

설정

npm install
cp .env.example .env   # fill in MAIL_MCP_API_TOKEN and one MAILMCP_PASS_<ID> per account

config/accounts.json.example을 config/accounts.json으로 복사합니다(이 파일은 gitignored 처리되며, 이 파일에도 비밀번호는 없습니다. 비밀번호는 오직 .env에만 있습니다):

[
  {
    "id": "example",
    "user": "user@example.com",
    "imap": { "host": "imap.example.com", "port": 993, "secure": true },
    "smtp": { "host": "smtp.example.com", "port": 465, "secure": true }
  }
]

id: "example" 계정의 비밀번호는 MAILMCP_PASS_EXAMPLE에서 읽습니다.

node index.js

기본적으로 127.0.0.1:4900에서 실행됩니다(MAIL_MCP_PORT 참조). 호스트 외부에서 접근해야 하는 경우 TLS를 사용하는 리버스 프록시 뒤에 배치하세요.

Related MCP server: Agent Email

systemd

예제 유닛은 deploy/mail-mcp.service에 있으며, /etc/systemd/system/으로 복사하고 경로를 조정하면 /root/mail-mcp/.env의 EnvironmentFile을 통해 비밀을 로드합니다.

인증

모든 REST 및 MCP 요청은 Authorization: Bearer <MAIL_MCP_API_TOKEN>이 필요합니다.

테스트

npm test              # run once
npm run test:coverage # run with coverage report

커버리지는 순수/로직 모듈(lib/schemas.js, lib/accounts.js, lib/webhooks-store.js)을 다룹니다. lib/mailclient.js와 lib/idle-watcher.js는 실제 IMAP/SMTP 서버와 통신하며, 단위 테스트 대신 수동 엔드투엔드 테스트를 통해 실행됩니다. 이들은 커버리지 배지에서 제외되어 오해를 피합니다.