XenoXilus/outlook-mcp

Microsoft Graph API를 통해 AI 어시스턴트가 Microsoft Outlook 이메일 및 캘린더와 상호작용할 수 있도록 지원하는 Model Context Protocol (MCP) 서버입니다.

이메일 작업 (Email Operations): 이메일 읽기, 검색, 전송, 답장 및 첨부 파일 다운로드
SharePoint 통합 (SharePoint Integration): 공유 링크 또는 직접 파일 ID를 통해 SharePoint 파일에 액세스합니다. 이메일을 통해 공유된 파일을 다운로드합니다.
캘린더 관리 (Calendar Management): 캘린더 이벤트 및 약속 확인 및 관리
Office 문서 처리 (Office Document Processing): PDF, Word, PowerPoint, Excel 파일을 파싱하여 추출된 텍스트 콘텐츠를 제공합니다.
대용량 파일 지원 (Large File Support): MCP 응답 크기 제한을 초과하는 파일을 자동으로 처리합니다.

설치 방법을 선택하세요:

방법	권장 대상
DXT 확장 프로그램	Claude Desktop 사용자
CLI 설정	Claude Code, mcp CLI, 기타 MCP 클라이언트

사전 요구 사항: 설치하기 전에 Client ID와 Tenant ID를 얻기 위해 Azure 애플리케이션을 설정해야 합니다.

Claude Desktop 사용자의 경우, DXT 확장이 가장 간단한 설치 경험을 제공합니다.

옵션 1: 사전 빌드된 확장 프로그램 다운로드

Releases 페이지에서 outlook-mcp.dxt를 다운로드합니다.
Claude Desktop에서 Settings→Extensions로 이동합니다.
Install from file을 클릭하고 .dxt 파일을 선택합니다.
안내에 따라 Azure Client ID, Tenant ID 및 선택 사항인 다운로드 디렉토리를 입력합니다.

옵션 2: 소스에서 빌드

클론 및 종속성 설치:
git clone https://github.com/XenoXilus/outlook-mcp.git cd outlook-mcp npm install
DXT CLI 설치:
npm install -g @anthropic-ai/dxt
확장 프로그램 패키징:
dxt pack . outlook-mcp.dxt
생성된 .dxt 파일을 위와 동일하게 Claude Desktop에 설치합니다.

CLI 기반 MCP 클라이언트 (Claude Code, mcp CLI 등)의 경우, 서버를 직접 구성합니다.

1. 클론 및 설치:

git clone https://github.com/XenoXilus/outlook-mcp.git
cd outlook-mcp
npm install

2. MCP 클라이언트 구성:

다음 내용을 MCP 서버 구성에 추가하세요 (위치는 클라이언트마다 다릅니다):

{
"outlook-mcp": {
"command": "node",
...

일반적인 설정 파일 위치:

Claude Code:~/.claude.json

또는 프로젝트 레벨의 .mcp.json

mcp CLI:~/.config/mcp/servers.json

3. 대안: 환경 변수 (Environment Variables) 사용

설정 파일에 env를 지정하는 대신, 셸(shell)에서 변수를 내보낼(export) 수 있습니다:

export AZURE_CLIENT_ID="your-azure-client-id"
export AZURE_TENANT_ID="your-azure-tenant-id"
export MCP_OUTLOOK_WORK_DIR="/optional/download/directory"

이 MCP 서버를 사용하려면 Microsoft Azure에 애플리케이션을 등록해야 합니다.

Azure Portal로 이동하여 "App registrations"를 검색합니다.
New registration을 클릭합니다.
- Name: Outlook MCP (또는 유사한 이름)
- Supported account types: Accounts in this organizational directory only (Single tenant)
- Redirect URI: Web을 선택하고 http://localhost/callback을 입력합니다.
Register를 클릭합니다.
사이드바에서 Authentication으로 이동합니다.
"Advanced settings" 아래에서 Allow public client flows를 Yes로 설정합니다.
Save를 클릭합니다.
Overview 페이지에서 다음을 복사합니다:
- Application (client) ID $\rightarrow$ 이것이 AZURE_CLIENT_ID입니다.
- Directory (tenant) ID $\rightarrow$ 이것이 AZURE_TENANT_ID입니다.
사이드바에서 API permissions로 이동합니다.
Add a permission $\rightarrow$ Microsoft Graph $\rightarrow$ Delegated permissions를 클릭합니다.
다음 권한들을 추가합니다:
- Mail.Read, Mail.ReadWrite, Mail.Send
- Calendars.Read, Calendars.ReadWrite
- User.Read, MailboxSettings.Read
- Files.Read.All, Files.ReadWrite.All
- Sites.Read.All, Sites.ReadWrite.All
- offline_access
Add permissions를 클릭합니다.
(선택 사항) 관리자라면, 사용자에게 동의 프롬프트를 표시하지 않도록 Grant admin consent를 클릭합니다.

참고: 클라이언트 비밀(client secret)은 필요하지 않습니다 (PKCE 인증 흐름 사용).

개인 Microsoft 계정도 Azure에 앱을 등록할 수 있습니다:

개인 Microsoft 계정(outlook.com, hotmail.com 등)으로 Azure Portal에 로그인합니다.
디렉터리(directory) 생성이 필요하다는 메시지가 표시되면, 안내에 따라 무료 Azure 디렉터리를 생성합니다.
비즈니스 계정의 경우 위와 동일한 단계를 따릅니다.
구성 시, 지원되는 계정 유형으로 Accounts in any organizational directory and personal Microsoft accounts를 사용하십시오.

변수 (Variable)	필수 여부	설명
`AZURE_CLIENT_ID`	예	Azure AD 애플리케이션 클라이언트 ID
`AZURE_TENANT_ID`	예	Azure AD 디렉터리 (tenant) ID
`MCP_OUTLOOK_WORK_DIR`	아니요	대용량 파일 저장용 디렉터리 (기본값은 시스템 임시 디렉터리)

대용량 첨부 파일이나 SharePoint 파일을 다운로드할 때, 서버는 응답이 MCP 1MB 제한을 초과할 것임을 자동으로 감지하고 대신 로컬 파일로 내용을 저장합니다.

MCP_OUTLOOK_WORK_DIR가 설정되어 있으면 대용량 파일이 이 디렉터리에 저장됩니다. 설정되어 있지 않으면 시스템 임시 디렉터리에 저장됩니다.
파일 이름은 충돌을 방지하기 위해 타임스탬프와 함께 자동으로 지정됩니다.
디스크 공간 관리를 위해 오래된 파일은 주기적으로 정리됩니다.

설치가 완료되면 AI 어시스턴트에게 다음과 같은 요청을 할 수 있습니다:

이메일 관리 (Email Management)

"이번 주에 읽지 않은 이메일을 보여줘"
"프로젝트 제안서에 대해 John이 보낸 모든 이메일을 찾아줘"
"Sarah가 보낸 마지막 이메일에 업데이트에 대한 감사 답장을 보내줘"
"오늘 회의 내용을 요약하는 이메일 초안을 작성해줘"

캘린더 (Calendar)

"내일 회의가 무엇이 있지?"
"다음 주 화요일 오후에 Alex와 30분간 통화 일정을 잡아줘"
"이번 주 남은 기간 동안 나의 가용 시간을 보여줘"

첨부 파일 및 SharePoint (Attachments & SharePoint)

"재무팀(Finance)에서 보낸 최신 이메일의 PDF 첨부 파일을 다운로드하고 요약해줘"
"이 SharePoint 링크의 내용을 가져와줘: [링크 붙여넣기]"
"이번 달 법무팀(Legal)에서 보낸 이메일에 어떤 파일들이 첨부되어 있었지?"

Office 문서 처리 (Office Document Processing)

서버는 다음을 자동으로 파싱(parse)합니다:

PDF 파일: 텍스트 콘텐츠 추출
Word 문서 (.docx): 텍스트 콘텐츠 추출
PowerPoint (.pptx): 슬라이드 텍스트 추출
Excel (.xlsx): 데이터를 구조화된 형식으로 파싱 (parse)

서버는 보안 인증을 위해 PKCE를 포함한 OAuth 2.0을 사용합니다:

첫 실행 시 Microsoft 인증을 위한 브라우저가 열립니다.
토큰은 암호화되어 로컬에 저장됩니다 (사용 가능한 경우 OS 키체인(keychain)을 사용하며, 그렇지 않으면 암호화된 파일 저장소를 사용합니다).
장기 사용을 위한 자동 토큰 갱신 (token refresh).
민감한 데이터는 평문 (plain text)으로 저장되지 않습니다.

앱은 다음과 같은 Microsoft Graph 권한을 요청합니다:

Mail.Read, Mail.ReadWrite, Mail.Send

이메일 액세스

Calendars.Read, Calendars.ReadWrite

캘린더 액세스

User.Read, MailboxSettings.Read

사용자 프로필

Files.Read.All, Files.ReadWrite.All

OneDrive/SharePoint 파일

Sites.Read.All, Sites.ReadWrite.All

SharePoint 사이트

offline_access

리프레시 토큰 (Refresh tokens)

문제: "Result exceeds maximum length" 오류
해결책: MCP_OUTLOOK_WORK_DIR가 설정되어 있고 쓰기 가능한지 확인하십시오.
대안: 작업 디렉토리가 구성되지 않은 경우 파일이 시스템 임시 디렉토리에 자동으로 저장됩니다.

문제: 인증 실패
해결책: Azure AD 앱 권한 및 클라이언트 ID (client ID)를 확인하십시오.
초기화: 저장된 토큰을 삭제하고 다시 인증하십시오.

문제: SharePoint 파일에 액세스할 수 없음
해결책: 공유 링크가 유효한지, 사용자가 액세스 권한을 가지고 있는지 확인하십시오.
대안: 가능한 경우 직접 파일 ID (file ID) 액세스를 사용하십시오.

outlook-mcp/
├── server/
│ ├── index.js # 메인 MCP 서버
...

npm test # 모든 테스트 실행
npm run test:watch # 워치 모드 (watch mode)
npm run test:benchmark # 성능 벤치마크 (performance benchmarks)

npm run test:graph # Graph API 연결 테스트

이 도구가 시간을 절약해 주었다면, 개발을 지원하는 것을 고려해 보세요!

MIT License

저장소 포크 (Fork)
기능 브랜치 (feature branch) 생성
테스트와 함께 변경 사항 적용
풀 리퀘스트 (pull request) 제출

XenoXilus/outlook-mcp

요약

핵심 포인트

댓글