使用说明

outlook-mcp

Microsoft Outlook 이메일을 조회, 검색, 발송할 수 있는 MCP(Model Context Protocol) 서버. Microsoft Graph API를 통해 메일박스에 접근합니다.

Claude Code, Claude Desktop, Cursor, Windsurf 등 MCP를 지원하는 모든 클라이언트에서 사용할 수 있습니다.

주요 기능

7개 도구 — 이메일 조회, 검색, 발송, 초안 작성, 폴더 관리
OAuth2 인증 — Microsoft Graph API, 토큰 자동 갱신
HTML 새니타이징 — 이메일 본문 안전하게 텍스트 변환
프로그레시브 검색 — 4단계 폴백으로 안정적인 검색

도구 목록

도구	설명
`list-emails`	받은편지함 또는 지정 폴더의 최근 이메일 목록 조회
`search-emails`	키워드, 발신자, 날짜 범위 등 다양한 조건으로 이메일 검색
`read-email`	특정 이메일의 전체 본문 읽기 (HTML → 텍스트 자동 변환)
`list-folders`	메일 폴더 계층 구조 및 아이템 수 확인
`send-email`	이메일 즉시 발송 (CC/BCC, HTML 지원)
`draft-email`	초안 이메일 작성 (임시보관함에 저장)
`mark-as-read`	이메일 읽음/안읽음 상태 변경

사전 요구사항

Node.js >= 20
Microsoft 365 계정 (회사 또는 개인)
Azure App Registration 완료 (아래 설정 참고)

Azure App Registration

Azure Portal > App registrations > New registration
Redirect URI: http://localhost:3333/auth/callback (Web 타입)
Certificates & secrets > New client secret 생성
API permissions > 다음 Delegated permissions 추가:
- offline_access
- User.Read
- Mail.Read (이메일 조회/검색)
- Mail.ReadWrite (초안 작성, 읽음 상태 변경)
- Mail.Send (이메일 발송)

설치

git clone <repository-url>
cd outlook-mcp
npm install

환경 설정

예제 파일을 복사하고 값을 입력합니다:

cp .env.example .env

# Azure Portal > App registrations > 앱 선택 > Overview
MS_CLIENT_ID=<Application (client) ID>

# Certificates & secrets > Client secrets > Value 컬럼 (ID가 아닌 Value를 복사!)
MS_CLIENT_SECRET=<Client secret VALUE>

# Overview > Directory (tenant) ID (선택, 미설정 시 "common" — 개인+회사 계정 모두 허용)
MS_TENANT_ID=<Tenant ID>

주의: .env에는 Client Secret이 포함됩니다. .gitignore에 이미 등록되어 있지만, 절대 git에 커밋하지 마세요. 실수로 커밋한 경우 Azure Portal에서 즉시 시크릿을 재생성하세요.

최초 인증

토큰이 없는 상태에서 최초 1회 실행:

npm run auth-server

브라우저에서 http://localhost:3333/auth 접속 → Microsoft 로그인 → 권한 동의 → 토큰이 자동 저장된다.

토큰 저장 위치:

macOS/Linux: ~/.outlook-mcp-tokens.json
Windows: C:\Users\{사용자명}\.outlook-mcp-tokens.json

이후에는 토큰이 자동 갱신되므로 다시 실행할 필요 없다 (90일 이상 미사용 시 재인증 필요).

참고: 이메일 발송(send-email), 초안 작성(draft-email), 읽음 상태 변경(mark-as-read) 기능을 사용하려면 Azure App에 Mail.ReadWrite와 Mail.Send 권한을 추가한 뒤 npm run auth-server로 재인증해야 합니다.

빌드 및 실행

# 빌드
npm run build

# 직접 실행
npm start

# 개발 모드 (TypeScript 직접 실행)
npm run dev

MCP 클라이언트에 등록

Claude Code:

claude mcp add outlook -s user -- node /path/to/outlook-mcp/dist/index.js

Claude Desktop / Cursor / 기타: 각 클라이언트의 MCP 서버 설정에서 node /path/to/outlook-mcp/dist/index.js를 stdio 서버로 등록합니다.

등록 후 바로 사용 가능:

> 받은편지함 최근 메일 5개 보여줘
> 지난주 김철수한테 온 메일 검색해줘
> 이 메일 본문 읽어줘 (ID: AAMk...)
> 메일 폴더 목록 보여줘
> kim@example.com에게 회의 안내 메일 보내줘
> 내일 보낼 보고서 초안 작성해줘

사용 예시

최근 이메일 조회

list-emails(folder: "inbox", count: 5)

조건 검색

search-emails(from: "kim@example.com", receivedAfter: "2026-03-10", count: 10)

이메일 읽기

read-email(id: "AAMkADAy...")

폴더 확인

list-folders(includeChildren: true)

이메일 발송

send-email(to: ["kim@example.com"], subject: "회의 안내", body: "내일 10시에 회의합니다.")

초안 작성

draft-email(subject: "주간 보고서", body: "이번 주 진행 상황...", to: ["team@example.com"])

기술 스택

TypeScript + Node.js >= 20
MCP SDK: @modelcontextprotocol/sdk v1.27+
스키마: zod (v4 서브패스 임포트)
인증: OAuth2 (Microsoft Graph API)
HTTP: Node.js 내장 fetch (외부 라이브러리 없음)

프로젝트 구조

outlook-mcp/
├── src/
│   ├── index.ts            # MCP 서버 진입점 + 도구 등록
│   ├── graph-client.ts     # Microsoft Graph API 클라이언트
│   ├── token-manager.ts    # OAuth2 토큰 관리
│   ├── auth-server.ts      # 최초 인증용 OAuth2 콜백 서버
│   └── tools/
│       ├── list-emails.ts    # 이메일 목록 조회
│       ├── search-emails.ts  # 이메일 검색
│       ├── read-email.ts     # 이메일 본문 읽기
│       ├── list-folders.ts   # 폴더 목록 조회
│       ├── send-email.ts     # 이메일 발송
│       ├── draft-email.ts    # 초안 작성
│       ├── mark-as-read.ts   # 읽음 상태 변경
│       ├── recipients.ts     # 수신자 파싱 유틸
│       └── format.ts         # 공통 포매팅 유틸
├── dist/                   # 빌드 출력
├── package.json
├── tsconfig.json
├── LICENSE
├── CLAUDE.md
├── README.md
├── .env                    # 환경변수 (gitignored)
├── .env.example            # 환경변수 템플릿

라이선스

MIT