outlook-mcp-server

Microsoft Graph API를 통해 개인 Hotmail / Outlook.com 사서함에 Claude(Desktop 또는 Code)가 읽기/쓰기 권한을 가질 수 있게 해주는 로컬 MCP 서버입니다. Microsoft ID 플랫폼에 대해 OAuth 2.0 인증 코드 흐름(PKCE 포함)을 사용합니다.

여섯 가지 도구를 제공합니다: list_messages, get_message, search_messages, send_message, create_draft, list_folders.

모든 것은 stdio를 통해 로컬에서 실행됩니다 — 호스팅 서비스가 없으며, 메일은 사용자의 컴퓨터와 Microsoft의 Graph API를 통해서만 전달됩니다.

작동 방식

• 인증: MSAL Node가 https://login.microsoftonline.com/consumers에 대해 인증 코드 + PKCE 흐름을 실행합니다(개인 계정 전용 — 테넌트 선택 참조). 수명이 짧은 로컬 HTTP 서버를 리디렉션 대상으로 사용합니다. 토큰(offline_access 갱신 토큰 포함)은 캐시되어 이후 실행 시 자동으로 갱신됩니다.

• 저장소: 토큰 캐시는 MSAL에 의해 직렬화되고, 로컬에서 생성된 키로 AES-256-GCM 암호화되어 ~/.outlook-mcp-server/token-cache.enc(모드 0600)에 기록됩니다. 키 자체는 ~/.outlook-mcp-server/cache.key(역시 0600)에 있습니다. 이 모델이 다루는(그리고 다루지 않는) 위협에 대해서는 보안 참고를 참조하세요.

• Graph 호출: 경량 fetch 기반 클라이언트가 현재 액세스 토큰으로 https://graph.microsoft.com/v1.0/...를 호출합니다.

• MCP 서버: @modelcontextprotocol/sdk 기반으로 구축되었으며 stdio를 사용하므로 Claude Desktop / Claude Code에서 자식 프로세스로 직접 실행할 수 있습니다.

Related MCP server: Outlook MCP Python

사전 요구 사항

• Node.js 18+

• Microsoft 계정(Hotmail, Outlook.com 또는 Live) — Claude가 액세스할 사서함입니다.

• 앱을 등록하기 위한 무료 Azure 계정(모든 Microsoft 계정으로 가능 — 유료 Azure 구독이 필요하지 않습니다).

1. 설치

git clone <this repo>
cd outlook-mcp-server
npm install

2. Azure Portal에서 앱 등록

이 등록을 통해 이 서버가 사용자를 대신하여 Microsoft Graph와 통신할 때 사용하는 클라이언트 ID가 발급됩니다. npm run setup(아래)이 이 과정을 대화형으로 안내하지만, 단계는 다음과 같습니다:

1. portal.azure.com으로 이동하여 Microsoft 계정으로 로그인합니다.

2. 앱 등록 → + 새 등록을 검색합니다.

3. 양식을 작성합니다:

   • 이름: 아무 이름이나, 예: outlook-mcp-server.

   • 지원되는 계정 유형: "개인 Microsoft 계정만". 이렇게 하면 앱이 회사/학교(Azure AD) 테넌트가 아닌 Hotmail/Outlook.com/Live 계정으로 제한됩니다.

   • 리디렉션 URI: 플랫폼 "공용 클라이언트/네이티브(모바일 및 데스크톱)", 값 http://localhost:8765/callback(또는 다른 포트 — npm run setup에서 묻는 값과 일치시키기만 하면 됩니다).

4. 등록을 클릭한 다음, 개요 페이지에서 애플리케이션(클라이언트) ID를 복사합니다.

5. API 권한 → + 권한 추가 → Microsoft Graph → 위임된 권한으로 이동하여 다음을 추가합니다:

   • Mail.Read

   • Mail.ReadWrite

   • Mail.Send

   • offline_access(보통 기본적으로 포함되어 있음)

   개인 Microsoft 계정의 위임된 권한은 관리자 동의가 필요하지 않습니다 — 3단계의 로그인 과정에서 직접 동의하게 됩니다.

6. (선택 사항, 고급) 공용 클라이언트 PKCE 흐름 대신 기밀 클라이언트를 사용하려면 웹 플랫폼 리디렉션 URI를 추가하고 인증서 및 비밀에서 클라이언트 비밀을 생성하세요. 대부분의 사용자는 이 단계를 건너뜁니다.

3. 설정 실행(인증 및 구성)

npm run setup

다음 단계를 수행합니다:

1. 위의 안내를 출력합니다.

2. 클라이언트 ID(및 선택적으로 비밀 / 테넌트 / 리디렉션 URI)를 입력받아 ~/.outlook-mcp-server/config.json에 저장합니다.

3. 로그인 및 동의를 위해 브라우저를 엽니다.

4. GET /me를 호출하여 이름/이메일을 출력함으로써 토큰이 작동하는지 확인합니다.

5. Claude 구성에 추가할 JSON 스니펫을 출력합니다(아래 참조).

나중에(토큰이 취소되었거나, 계정을 전환하거나, 기타 이유로) 앱 등록 세부 정보를 다시 입력하지 않고 재인증하려면:

npm run login

4. 빌드 및 Claude에 등록

npm run build

Claude Desktop — claude_desktop_config.json에 추가합니다 (macOS의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows의 경우 %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "outlook": {
      "command": "node",
      "args": ["/absolute/path/to/outlook-mcp-server/dist/src/index.js"]
    }
  }
}

Claude Code:

claude mcp add outlook -- node /absolute/path/to/outlook-mcp-server/dist/src/index.js

Claude Desktop / Claude Code를 다시 시작하면 아래 도구를 사용할 수 있습니다.

도구

모든 도구는 JSON(MCP 텍스트 콘텐츠)을 반환하며, Graph API 오류를 서버 충돌 대신 도구 오류로 표시합니다.

테넌트 선택

기본적으로 이 서버는 consumers 테넌트를 사용합니다 (https://login.microsoftonline.com/consumers). 이 테넌트는 개인 Microsoft 계정(Hotmail/Outlook.com/Live)만 허용합니다 — 회사/학교 계정은 로그인 시 거부됩니다. 개인 계정과 Azure AD 계정을 모두 지원해야 하는 경우 npm run setup 중에 테넌트를 common으로 설정하세요 (또는 OUTLOOK_MCP_TENANT=common 환경 변수 사용). 이 프로젝트는 개인 계정(consumers) 사례에 맞게 설계되고 테스트되었습니다.

구성 참고

모든 것은 npm run setup을 통해 설정할 수 있습니다(~/.outlook-mcp-server/config.json에 기록됨). 또는 환경 변수로 설정할 수 있으며, 환경 변수가 우선합니다 — .env.example 참조:

보안 참고

• 토큰 캐시는 로컬에서 생성된 AES-256-GCM 키(~/.outlook-mcp-server/cache.key, 모드 0600)로 암호화되어 저장됩니다. 이는 우발적 노출(실수로 인한 커밋, 백업, 공유 컴퓨터의 다른 권한 없는 사용자)을 방지하지만, 키가 암호화된 캐시와 같은 위치에 있으므로 이미 사용자 계정의 파일에 대한 읽기 권한이 있는 공격자에 대해서는 보호하지 못합니다. 더 강력한 보호를 원하면 src/auth/tokenCache.ts의 ICachePlugin을 OS 키체인(예: keytar 사용) 기반 구현으로 교체하세요 — 플러그인 인터페이스는 의도적으로 해당 파일 하나에만 격리되어 있습니다.

• ~/.outlook-mcp-server/(기본적으로 저장소 외부에 있음) 또는 OUTLOOK_MCP_CLIENT_SECRET이 포함된 .env 파일을 커밋하지 마세요.

• send_message는 이 서버 내부에서 확인 단계 없이 즉시 전송합니다 — Claude는 민감한 작업에 대해 호출하기 전에 사용자에게 의도를 확인하도록 되어 있습니다. 검토 단계가 필요하면 create_draft를 선호하세요.

• 요청되는 권한 범위는 Mail.Read, Mail.ReadWrite, Mail.Send, offline_access로 제한됩니다 — 일정, 연락처 또는 더 넓은 Mail.* 애플리케이션 수준 액세스는 없습니다.

문제 해결

• AADSTS50020 / "사용자 계정 ...이(가) 테넌트에 없습니다" — 개인 계정을 허용하지 않는 테넌트를 사용 중이거나, consumers에 회사/학교 계정으로 로그인하고 있는 것입니다. 앱 등록의 "지원되는 계정 유형"이 "개인 Microsoft 계정만"인지, OUTLOOK_MCP_TENANT가 consumers인지(두 유형을 모두 의도적으로 지원하려면 common) 확인하세요.

• AADSTS50011 / 리디렉션 URI 불일치 — ~/.outlook-mcp-server/config.json의 redirectUri는 Azure 앱 등록에 구성된 리디렉션 URI와 포트를 포함하여 정확히 일치해야 합니다.

• "로그인되지 않음" 도구 오류 — npm run login을 실행하세요.

• 설정/로그인 중 포트 이미 사용 중 — 다른 프로세스가 리디렉션 URI의 포트를 사용 중입니다. 해당 프로세스를 중지하거나, 앱 등록과 npm run setup을 다른 포트로 재구성하세요.

개발

npm run dev     # run the MCP server directly from TypeScript (stdio)
npm run build   # compile to dist/
npm run clean   # remove dist/

프로젝트 구조

src/
  index.ts            MCP server entrypoint (stdio transport)
  config.ts            Config loading (env + config file)
  auth/
    crypto.ts           AES-256-GCM file encryption helpers
    tokenCache.ts        MSAL ICachePlugin backed by crypto.ts
    msalClient.ts        MSAL app factory + silent token acquisition
    loginFlow.ts          Interactive loopback OAuth flow
  graph/
    client.ts            Generic Microsoft Graph fetch wrapper
    mail.ts               Mail-specific Graph calls
    types.ts              Graph response types
  tools/                 One file per MCP tool, registered in index.ts
scripts/
  setup.ts              Interactive one-time (and re-runnable) setup