Outlook MCP Server

Model Context Protocol 서버로, Claude를 Microsoft Outlook + Teams(이메일, 캘린더, 연락처, 작업, 파일, Teams 회의 녹화 및 대본)에 연결하며, Cloudflare Workers에 배포됩니다.

이 저장소를 포크하여 자신의 Cloudflare 계정에 배포하고, Microsoft Azure AD 앱을 등록한 뒤, Claude.ai를 자신의 worker에 연결하면 Claude가 자연어를 통해 Microsoft 365 데이터를 읽고 쓸 수 있습니다.

@bashco/mcp-toolkit 기반으로 구축되었습니다 — OAuth, 클라이언트별 bearer 토큰, 속도 제한, 구조화된 로깅, 타입 기반 도구 디스패치는 모두 공유 라이브러리에서 처리됩니다.

Claude가 사용할 수 있는 것 — 7개 도메인, 39개 도구

• 메일: 이메일 목록, 이메일 읽기, 검색, 답장, 전달, 삭제, 보내기, 폴더 간 이동, 초안 작성, 초안 업데이트, 초안 보내기, 예약 발송

• 캘린더: 이벤트 목록, 이벤트 발생 목록, 생성, 업데이트, 삭제, 이벤트 취소, 이벤트 응답

• 연락처: 목록, 연락처 생성, 연락처 업데이트

• 작업: 작업 목록 목록, 작업 목록, 작업 생성

• 파일: 파일 목록, 파일 공유

• Teams 회의: 최근 녹화 목록(탐색 시작점 — 지난 N일 동안 콘텐츠가 있는 회의를 찾으며, 입력이 필요 없음), 온라인 회의 찾기, 회의 녹화 목록, 회의 대본 목록, 대본 콘텐츠 가져오기. 각 회의별 도구는 meeting_id, calendar_event_id, join_url 중 아무거나 허용하므로 예약된 회의(이벤트를 통해 확인), 임시 / Meet-now 통화(Teams 채팅에서 붙여넣은 join URL을 통해 확인), 직접 ID 조회가 모두 작동합니다.

• 대화: 대화 가져오기(전체 스레드)

• 설정: 사서함 설정 가져오기, 부재 중 설정

배포 후 tools/list MCP 엔드포인트에서 전체 라이브 카탈로그를 확인할 수 있습니다.

Related MCP server: MCP Outlook Server

인증 작동 방식

두 계층으로 구성됩니다:

1. Claude.ai ↔ 사용자 worker — 표준 MCP OAuth 2.0 + PKCE 흐름. 각 Claude 클라이언트는 고유한 bearer 토큰을 받습니다. 사용자의 MCP_APPROVAL_CODE는 /authorize에서 한 번 붙여넣어 해당 bearer를 발급하는 데 사용됩니다.

2. 사용자 worker ↔ Microsoft Graph — 프록시 OAuth. 배포된 worker의 /oauth/start를 방문하여 Microsoft 인증을 한 번 수행합니다. 새로 고침 토큰은 Cloudflare KV에 암호화되어 저장됩니다. 새로 고침은 자동으로 이루어집니다.

설정 — 자신의 사본 배포

사전 요구 사항

• Cloudflare 계정(무료 플랜으로 충분)

• Wrangler CLI 설치 및 로그인(wrangler login)

• Node.js 22+

• entra.microsoft.com에서 Azure AD 앱을 등록할 수 있는 Microsoft 계정(개인, 회사 또는 학교)

1. 포크 및 클론

git clone https://github.com/<your-username>/outlook-mcp
cd outlook-mcp
npm install

2. KV 네임스페이스 생성

wrangler kv:namespace create OAUTH_KV

Wrangler가 다음과 같은 내용을 출력합니다:

🌀 Creating namespace with title "outlook-mcp-OAUTH_KV"
✨ Success! Add the following to your configuration file:
[[kv_namespaces]]
binding = "OAUTH_KV"
id = "abc123def456..."

wrangler.jsonc를 편집하고 kv_namespaces 아래의 기존 id를 방금 wrangler가 출력한 값으로 교체합니다.

wrangler.jsonc는 의도적으로 커밋됩니다 — Wrangler와 CI 배포 모두 이 파일이 필요하며, 비밀 정보는 포함하지 않습니다(KV 네임스페이스 id, 공개 Azure 클라이언트 id, worker URL만 포함). wrangler.jsonc.example은 깨끗한 사본에서 시작하려는 경우 자리 표시자가 포함된 동일한 구조를 제공합니다. 실제 비밀 정보는 wrangler secret put을 통해 전달되며 이 파일에 절대 나타나지 않습니다.

3. Microsoft Azure AD 앱 등록

1. entra.microsoft.com → Identity → Applications → App registrations → New registration으로 이동

2. 이름: 아무거나(예: "Claude Outlook MCP")

3. 지원되는 계정 유형:

   • 단일 테넌트로 제한하려면 "이 조직 디렉터리의 계정만"

   • 가장 광범위한 지원을 위해 "모든 조직 디렉터리의 계정 및 개인 Microsoft 계정"

4. 리디렉션 URI: 지금은 비워 둡니다 — 6단계 후에 다시 돌아옵니다

5. 등록 클릭

6. 앱의 개요 페이지에서 다음을 기록합니다:

   • 애플리케이션(클라이언트) ID → 이것이 MICROSOFT_CLIENT_ID입니다

   • 디렉터리(테넌트) ID → 이것이 MICROSOFT_TENANT_ID입니다(다중 테넌트 + 개인 계정 지원을 위해 문자열 common을 사용할 수도 있음)

7. API 권한 → 다음 Microsoft Graph 위임 권한을 추가합니다:

   • Mail.ReadWrite, Mail.Send

   • Calendars.ReadWrite

   • Contacts.ReadWrite

   • Tasks.ReadWrite

   • Files.Read.All(쓰기 가능한 파일 도구를 원하면 Files.ReadWrite.All)

   • User.Read

   • offline_access(새로 고침 토큰에 필요)

   • MailboxSettings.ReadWrite

   • Sites.Read.All

   • OnlineMeetings.Read

   • OnlineMeetingRecording.Read.All — 관리자 동의 필요

   • OnlineMeetingTranscript.Read.All — 관리자 동의 필요

   두 .Read.All 권한을 추가한 후 API 권한 페이지에서 "[테넌트 이름]에 대한 관리자 동의 허용" 을 클릭합니다. 관리자 동의가 없으면 회의 녹화 / 대본 도구가 403을 반환합니다.

8. 인증서 및 비밀 → 새 클라이언트 비밀 → 값 기록(1Password에 저장). 이것이 MICROSOFT_CLIENT_SECRET입니다. 한 번만 볼 수 있으므로 즉시 복사하세요.

4. wrangler.jsonc 업데이트

wrangler.jsonc를 편집하고 다음 두 항목을 교체합니다:

• vars.MICROSOFT_CLIENT_ID — 3.6단계의 애플리케이션 ID로

• vars.MICROSOFT_TENANT_ID — 3.6단계의 디렉터리 ID로(또는 common)

5. 비밀 설정

새 승인 코드 생성:

openssl rand -base64 32

비밀번호 관리자에 저장한 후 Cloudflare에 푸시:

wrangler secret put MCP_APPROVAL_CODE          # paste the value from above
wrangler secret put MICROSOFT_CLIENT_SECRET    # from Step 3.8

6. 첫 배포(worker URL 확인용)

npm run deploy

Wrangler가 worker URL을 출력합니다 — https://outlook-mcp.<your-account>.workers.dev 형식입니다. 저장하세요.

7. WORKER_URL 및 Microsoft 리디렉션 URI 업데이트

두 가지 업데이트가 필요합니다:

a) wrangler.jsonc 편집 — vars 아래에서 WORKER_URL을 6단계의 URL로 교체합니다.

b) Azure AD 앱에서(entra.microsoft.com → 앱 → Authentication → Add a platform → Web) 리디렉션 URI를 <your-worker-url>/oauth/callback으로 설정합니다. 이 설정이 없으면 Microsoft가 OAuth 흐름을 거부합니다.

그런 다음 재배포:

npm run deploy

8. Microsoft 연결(일회성)

브라우저에서 <your-worker-url>/oauth/start를 방문합니다. MCP_APPROVAL_CODE를 붙여넣습니다. Microsoft로 리디렉션되어 3.7단계의 범위에 로그인하고 동의합니다. 동의 후 암호화된 업스트림 토큰이 OAUTH_KV에 저장됩니다. 이후 새로 고침은 자동으로 이루어집니다.

<your-worker-url>/oauth/status를 방문하여 연결을 확인할 수 있습니다 — connected: true로 표시되어야 합니다.

9. Claude.ai 연결

1. Claude.ai에서 Settings → Integrations → Add MCP server로 이동

2. 서버 URL: <your-worker-url>/mcp

3. Claude.ai가 worker의 /authorize 페이지로 리디렉션합니다

4. MCP_APPROVAL_CODE를 붙여넣고 확인

5. 연결 완료 — 이제 Claude가 38개의 Outlook + Teams 도구를 사용할 수 있습니다

이메일 서명

선택 사항. 구성된 경우 Worker가 전송 시 서명을 추가하므로 호출 에이전트가 서명을 재현할 필요가 없습니다 — 의역, 잘림, 누락이 불가능합니다.

send_email, schedule_send, reply_to_email, forward_email, create_draft, update_draft, create_reply_draft, create_reply_all_draft, create_forward_draft 중 아무 도구에 include_signature: true를 전달하세요. 기본값은 false이므로 기존 호출자에게는 영향이 없습니다.

초안의 경우 서명은 초안 생성 시점에 주입되며 전송 시점이 아닙니다 — send_draft는 id만 받고 본문을 건드리지 않습니다. 즉, 서명된 본문을 보내기 전에 검토하게 됩니다. update_draft에서 이 플래그는 새 body도 함께 전달할 때만 적용됩니다(그렇지 않으면 서명할 내용이 없고, 서명만 있는 본문으로 초안을 대체하게 되므로). 이 경우 응답 notes에 보고되며 초안을 조용히 지우지 않습니다.

캘린더 초대

create_calendar_event 및 update_calendar_event는 동일한 include_signature 플래그를 허용하며, 이벤트 설명에 서명을 추가합니다. 이메일과 동일한 SIGNATURE_HTML 블록을 재사용합니다 — 마케팅 클릭 유도 버튼을 포함 — 따라서 내부 회의보다 고객 대상 초대에 더 적합합니다. 이것이 이벤트별로 옵트인인 이유입니다. update_calendar_event는 update_draft와 동일한 보호 장치를 따릅니다: 새 description도 함께 전달할 때만 플래그가 적용됩니다.

설정

cp signature-block.example.html signature-block.html   # then edit it
wrangler secret put SIGNATURE_HTML < signature-block.html
wrangler secret put SIGNATURE_LOGO_URL                 # paste your HTTPS logo URL

signature-block.html은 의도적으로 gitignore 처리됩니다. 서명은 배포 구성이지 소스가 아닙니다: 커밋된 서명을 상속받은 포크는 다른 사람의 이름, 전화번호, 예약 링크가 포함된 메일을 보내게 됩니다. 자리 표시자 signature-block.example.html만 커밋됩니다.

SIGNATURE_HTML 내부의 __LOGO_URL__ 토큰은 런타임에 SIGNATURE_LOGO_URL로 대체됩니다.

로고는 HTTPS를 통해 공개적으로 접근 가능해야 합니다. 메일 클라이언트는 수신자의 기기에서 로고를 가져옵니다 — 수신자 기기는 사용자 네트워크, Worker의 바인딩, 또는 보유한 자격 증명에 접근할 수 없습니다. 비공개, 인증 필요, 또는 localhost URL은 모든 사람에게 깨진 이미지로 표시됩니다. SIGNATURE_LOGO_URL이 설정되지 않은 경우 깨진 src를 내보내는 대신 <img>가 완전히 제거됩니다.

SIGNATURE_HTML이 설정되지 않은 경우 플래그는 조용한 no-op입니다 — 메일은 서명 없이 전송됩니다. 구성되지 않은 배포는 절대 오류를 발생시키지 않습니다.

동작

• HTML 강제. 일반 텍스트 본문의 서명은 원시 마크업으로 렌더링되므로 플래그가 설정될 때마다 body_type이 html로 재정의됩니다. body_type: "text"를 명시적으로 전달한 경우 재정의는 도구 응답의 notes에 보고되며 조용히 적용되지 않습니다.

• 일반 텍스트 본문은 이스케이프된 후 줄바꿈이 <br>이 됩니다. 따라서 강제 HTML 전환에서도 줄바꿈이 유지되고 잘못된 < 문자가 마크업이 될 수 없습니다.

• 멱등성. 본문에 이미 서명이 포함된 경우 — Worker 자체 마커 또는 서명의 고유 텍스트로 인식 — 두 번 추가되지 않습니다.

• 답장 및 전달은 인용된 원본 위에 서명을 배치하며, 전체 스레드의 맨 아래가 아닙니다.

• 빈 본문은 선행 빈 줄 없이 서명만 전송합니다.

보안 참고 사항

서명은 호출자의 본문이 정화된 후에 연결됩니다. 이는 의도적이고 중요한 설계입니다: sanitizeOutboundHtml은 모든 style= 속성(속성 전용 XSS 싱크)을 제거하며, 서명은 전적으로 인라인 스타일로 구성되므로 정화기를 통과시키면 로고 크기, 구분선, CTA 버튼이 제거됩니다.

두 문자열은 신뢰 수준이 다릅니다. 본문은 에이전트가 제공하고 신뢰할 수 없으므로 여전히 완전히 정화됩니다. 서명은 wrangler secret put으로 설정되는 운영자 제공 배포 구성입니다 — 해당 비밀을 설정할 수 있는 사람은 이미 Worker를 완전히 변경할 수 있습니다. src/signature.ts 참조.

로컬 개발

cp .dev.vars.example .dev.vars   # fill in MCP_APPROVAL_CODE + MICROSOFT_CLIENT_SECRET; .dev.vars is gitignored
npm test                          # 171 tests via vitest with workers pool
npm run typecheck                 # tsc --noEmit
npm run dev                       # wrangler dev — local at http://localhost:8787

엔드포인트

• GET /.well-known/oauth-authorization-server — OAuth 메타데이터 (공개)

• GET /.well-known/oauth-protected-resource — 리소스 메타데이터 (공개)

• GET /authorize — 승인 코드 붙여넣기 페이지 (공개)

• POST /approve — 승인 코드 제출 (속도 제한)

• POST /token — OAuth 토큰 교환 (속도 제한)

• POST /register — RFC 7591에 따른 동적 클라이언트 등록 (속도 제한)

• GET /oauth/start — Microsoft OAuth 흐름 시작 (MCP_APPROVAL_CODE로 게이트됨)

• GET /oauth/callback — Microsoft OAuth 리디렉션 대상

• GET /oauth/status — 연결 상태 확인 (MCP_APPROVAL_CODE로 게이트됨)

• POST /mcp — JSON-RPC 도구 디스패치 (bearer 보호, 속도 제한)

스택

• Cloudflare Workers (compatibility_date 2025-04-28, nodejs_compat)

• TypeScript (strict)

• Hono v4

• Zod v4

• Vitest with @cloudflare/vitest-pool-workers (테스트 171개)

• @bashco/mcp-toolkit — 공유 OAuth/암호화/속도 제한/디스패치 플러밍

보안 아키텍처 하이라이트

• 발신 이메일 미리보기에 대한 엔티티 정규화를 포함한 2패스 HTML 살균기

• 발신 HTTP에 대한 32비트 IP 정규화를 포함한 SSRF 가드

• 구조화된 오류 반환을 위한 Microsoft Graph odata 오류 봉투 파싱

• 감사 가능성을 위한 src/tools/ 아래의 도메인별 도구 파일 (메일, 캘린더, 연락처, 작업, 파일, 회의, 설정)

지속적 배포

.github/workflows/deploy.yml는 main에 푸시할 때마다 vitest run을 실행한 다음 Cloudflare에 배포합니다. 포크에서 활성화하려면 두 개의 리포지토리 시크릿을 설정하세요:

• CLOUDFLARE_API_TOKEN — dash.cloudflare.com/profile/api-tokens에서 생성 ("Edit Cloudflare Workers" 템플릿 사용)

• CLOUDFLARE_ACCOUNT_ID — Cloudflare 대시보드 오른쪽 하단에서 확인

기여

이슈와 PR은 github.com/doublebash/outlook-mcp에서 환영합니다.

기본 OAuth/암호화/속도 제한 코드 변경의 경우, 툴킷은 github.com/doublebash/mcp-toolkit에 있습니다 — 해당 리포지토리에 이슈를 등록하세요.

보안

취약점을 발견하셨나요? 공개 이슈를 열지 마세요. GitHub에서 비공개 보안 권고를 열어주세요.

라이선스

MIT — 저작권 (c) 2026 Bashar Basheer.