useful-outlook-mcp

적절한 OAuth2와 에이전트에 최적화된 도구를 갖춘 Microsoft Outlook용 원격 MCP 서버입니다.

기능

• 규격 준수: RFC 9728/8414 OAuth 메타데이터, RFC 7591 동적 클라이언트 등록

• 무상태 OAuth: 토큰은 서버가 아닌 클라이언트가 관리—OAuth가 의도한 대로

• 에이전트 최적화 도구: 도구 설명에 광범위한 프롬프트 엔지니어링 적용

• 동적 범위: OAuth 범위가 활성화된 도구에 맞게 자동 조정

• 프로덕션 준비 완료: Docker, 속도 제한, 읽기 전용 모드, 도구 필터링

Related MCP server: M365 MCP Server

빠른 시작

npm install
npm run build
npm start  # Server at http://localhost:3000

필요한 환경:

MS365_MCP_CLIENT_ID=your-azure-ad-client-id
MS365_MCP_CLIENT_SECRET=your-azure-ad-client-secret
MS365_MCP_TENANT_ID=your-tenant-id  # or 'common'

Azure AD 설정

1. Azure Portal → Microsoft Entra ID → 앱 등록 → 새로 만들기

2. 위임된 권한 추가: User.Read, Mail.Read, Mail.ReadWrite, Mail.Send, Calendars.Read, Calendars.ReadWrite, Calendars.Read.Shared, Place.Read.All, People.Read, offline_access

3. 리디렉션 URI 추가: http://localhost:6274/oauth/callback (MCP Inspector용)

4. 인증서 및 비밀 → 새 클라이언트 비밀 → 값을 복사합니다.

5. 클라이언트 ID, 클라이언트 비밀, 테넌트 ID를 .env에 복사합니다.

도구

메일

list-mail-folders · list-mail-messages · search-mail · get-mail-message · send-mail · create-draft-mail · reply-mail · reply-all-mail · create-reply-draft · create-reply-all-draft · delete-mail-message · move-mail-message

일정

list-calendars · list-calendar-events · search-calendar-events · find-meeting-times · get-calendar-event · get-calendar-view · create-calendar-event · update-calendar-event · delete-calendar-event

사람

lookup-contact-email

회의실 검색

대면 회의의 경우 find-meeting-times는 자동으로:

• 조직 전체의 사용 가능한 모든 회의실을 가져옵니다.

• 참석자와 함께 가용성 확인에 포함합니다.

• 빈 회의실을 위치(도시/건물)별로 그룹화합니다.

• 예약 가능한 이메일 주소가 있는 회의실만 반환합니다.

회의실 검색을 활성화하려면 isOnlineMeeting: false로 설정하세요. 온라인 회의(기본값: true)의 경우 Teams 모임 링크가 자동으로 생성됩니다.

필요한 범위: Place.Read.All (Azure AD 앱 권한에 추가)

구성

Docker

GitHub Container Registry에서:

docker run -p 3000:3000 \
  -e MS365_MCP_CLIENT_ID=xxx \
  -e MS365_MCP_CLIENT_SECRET=xxx \
  -e MS365_MCP_TENANT_ID=xxx \
  ghcr.io/Leonine-Studios/useful-outlook-mcp:latest

또는 로컬에서 빌드:

docker build -t useful-outlook-mcp .
docker run -p 3000:3000 \
  -e MS365_MCP_CLIENT_ID=xxx \
  -e MS365_MCP_CLIENT_SECRET=xxx \
  -e MS365_MCP_TENANT_ID=xxx \
  useful-outlook-mcp

엔드포인트

테스트

npm run dev
npx @modelcontextprotocol/inspector  # Connect to http://localhost:3000/mcp

설계 노트

기존 서버의 문제점

1. 레거시 아키텍처: stdio 기반으로 만들어지고 HTTP가 얹혀 있습니다. 이 서버는 HTTP 네이티브입니다.

2. 잘못된 OAuth 처리: 대부분의 서버는 토큰을 서버 측에 저장합니다. 이 서버는 무상태(stateless)입니다—토큰은 Authorization 헤더를 통해 요청별로 전달되며 저장되지 않습니다.

3. 생각 없이 만든 도구: 일반적인 서버는 안내 없이 API 엔드포인트를 1:1로 매핑합니다. 에이전트는 API의 특이점이나 다단계 워크플로를 알지 못해 실사용에서 실패합니다.

무엇이 다른가

모든 도구에는 다음이 포함됩니다:

• 대안과 비교해 언제 사용해야 하는지

• 알려진 Graph API 특이점(매우 많음)

• 다단계 작업을 위한 워크플로 안내

• 실패하는 매개변수 조합

예: find-meeting-times는 이메일 주소가 필수이며(이름은 작동하지 않음), search-mail을 사용해 이름에서 이메일을 찾는 방법, OrganizerUnavailable의 의미, 그리고 isOrganizerOptional=true에는 사용자 확인이 필요하다는 점을 설명합니다.

알려진 Graph API 특이점

• 메일 보낸 사람 필터링: from/emailAddress/address에 대한 eq는 신뢰할 수 없음—startswith() 사용

• 메일 받는 사람 필터링: $filter로 받는 사람/참조/숨은 참조를 필터링할 수 없음—$search를 사용해야 함

• 일정 주최자 필터링: 주최자 이메일에 대한 $filer는 500을 반환—클라인언트 측에서 필터링됨 | 동시성: 병렬 호출은 MailboxConcurrency` 오류를 반환할 수 있음

• 검색 + 정렬: $search는 $orderby와 결합할 수 없음

라이선스

MIT