Softeria/ms-365-mcp-server

A Model Context Protocol (MCP) server for interacting with Microsoft 365 and Microsoft Office services through the Graph API

📦 ms-365-mcp-server란?

Microsoft 365(Graph) 기능을 Model-Context-Protocol(MCP) 도구로 노출하는 Node-JS 서버입니다. 각 도구는 하나의 Graph API 엔드포인트(예: list-mail-messages, get-drive-item)에 매핑되며, Claude Desktop, Claude Code CLI 또는 기타 MCP 호환 프론트엔드와 같은 LLM 기반 어시스턴트에서 호출할 수 있습니다.

🎯 핵심 목적

방대한 Microsoft 365 Graph 범위를 LLM이 커스텀 HTTP 코드를 작성하지 않고도 호출할 수 있는 안정적이고 선언적인 도구 세트로 변환합니다.
두 가지 출력 인코딩을 제공합니다 – 일반 JSON(기본값)과 실험적인 TOON 형식. TOON은 목록형 데이터의 토큰 수를 30~60% 줄여줍니다.
개인 및 조직(업무/학교) 계정, 여러 클라우드(글로벌 및 중국), 그리고 단일 서버 인스턴스에서의 멀티 계정 사용을 지원합니다.

⚙️ 주요 기능(README에 설명된 내용)

기능	제공되는 것
인증	MSAL 기반 디바이스 코드 플로우(기본값), `--http` 모드 실행 시 OAuth 2.1, 또는 `MS365_MCP_OAUTH_TOKEN`을 통한 자체 토큰 사용.
도구 범위	전체 Graph API(메일, 캘린더, OneDrive, Teams, SharePoint, Planner 등)를 다루는 300개 이상의 자동 생성 도구.
프리셋 및 필터링	`--preset`, `--enabled-tools` 정규식, 또는 `--allowed-scopes`를 사용하여 도구 세트를 필요한 것만으로 줄이고 토큰 사용량과 필요한 권한을 감소시킵니다.
읽기 전용 모드	우발적인 쓰기로부터의 안전장치(`--read-only`).
동적 권한 탐색	`--list-permissions`는 현재 설정이 요청할 정확한 Graph 스코프를 표시하여 관리자가 사전 동의 승인을 돕습니다.
출력 형식	JSON(예쁘게 출력) 또는 실험적인 TOON(Token-Oriented Object Notation)으로 LLM 호출 비용을 절감.
멀티 계정 지원	여러 Microsoft 계정에 로그인 가능. 각 도구 호출에서 `account` 인자(이메일 또는 MSAL homeAccountId)를 지정할 수 있습니다.
엔터프라이즈 제어	`--allowed-scopes`로 토큰 요청을 좁히고, `--extra-scopes`로 커스텀 스코프를 추가. SharePoint는 `Sites.Selected`로 제한 가능.
CLI 또는 Docker로 배포 가능	`npx @softeria/ms-365-mcp-server …`로 실행하거나 컨테이너화. HTTP 모드는 `--public-url`을 사용하여 리버스 프록시 뒤에 작동합니다.

🛠️ 일반적인 워크플로

설치 – npm i -g @softeria/ms-365-mcp-server(또는 npx로 실행).
인증 – npx @softeria/ms-365-mcp-server --login(디바이스 코드) 또는 OAuth를 위해 --http 모드로 시작.
구성 – README의 JSON 스니펫을 사용하여 LLM 클라이언트(Claude Desktop, Claude Code CLI, Open WebUI 등)에 서버 추가.
모드 선택 – 기본값은 개인용. Teams, SharePoint, 공유 메일박스 등을 잠금 해제하려면 --org-mode 추가.
도구 호출 – LLM이 { "tool": "list-mail-messages", "arguments": { "account": "work@company.com" } }와 같은 요청을 보내면, 서버가 Graph와 통신하여 JSON 또는 TOON을 반환합니다.

📦 설치 및 빠른 시작

# 직접 실행(글로벌 설치 불필요)
npx @softeria/ms-365-mcp-server --login   # 디바이스 코드 플로우
# 도구 테스트
npx @softeria/ms-365-mcp-server --tool list-mail-messages

Docker의 경우:

docker run -p 3000:3000 ghcr.io/softeria/ms-365-mcp-server:latest --http

그 다음 MCP 호환 클라이언트를 http://localhost:3000/mcp로 지정합니다.

🔗 언급된 통합 지점

Claude Desktop – 설정 → 개발자에 추가.
Claude Code CLI – claude mcp add ms365 -- npx -y @softeria/ms-365-mcp-server ….
Open WebUI – HTTP 모드, OAuth 2.1, UI에서 클라이언트 등록.
커스텀 클라이언트 – MCP(stdio 또는 HTTP를 통한 JSON)를 처리할 수 있는 모든 도구.

📚 언제 사용해야 하나요?

사용자의 Outlook 메일, 캘린더 또는 OneDrive 파일을 읽기/쓰기해야 하는 AI 어시스턴트 구축.
엄격한 권한 경계를 준수하면서 Teams 채팅, SharePoint 목록 또는 Planner 작업과 상호작용해야 하는 엔터프라이즈 봇.
토큰 효율성이 중요한 모든 LLM 기반 워크플로 – 대규모 목록 응답의 비용을 줄이기 위해 TOON으로 전환.
단일 서버 인스턴스가 여러 사용자의 Microsoft 계정을 관리하는 멀티 테넌트 SaaS.

⚠️ README의 제한 사항 / 참고 사항

TOON은 실험적으로 표시됨 – 변경될 수 있음.
HTTP 모드에서는 인증 도구가 기본적으로 비활성화됩니다. 필요 시 --enable-auth-tools로 활성화.
기본 Softeria Azure 앱에는 제한된 권한 세트가 있습니다. 추가 스코프를 요청하려면 자체 Azure AD 앱(MS365_MCP_CLIENT_ID 등)을 제공해야 합니다.
--allowed-scopes는 권한을 좁히는 것만 가능합니다. 넓히려면 --extra-scopes가 필요합니다.
고정(MS365_MCP_EXPECTED_USERNAME / --expected-home-account-id)은 선택 사항이지만 헤드리스 배포에 유용합니다.

📖 더 알아보기

소스 코드 – src/endpoints.json은 모든 생성된 도구를 나열합니다.
배포 가이드 – docs/deployment.md(리버스 프록시 설정 참조).
TOON 형식 – 링크된 GitHub 저장소 github.com/toon-format/toon 참조.

TL;DR

ms-365-mcp-server는 Microsoft 365 Graph API를 Model-Context-Protocol을 통해 LLM이 호출할 수 있는 대규모 권한 인식형 도구상자로 변환하는 완성된 브리지입니다. 인증, 권한 스코핑, 멀티 계정 관리를 처리하고 토큰 절약형 출력 형식을 제공하므로, 실제 Microsoft 365 데이터가 필요한 AI 어시스턴트를 구축하는 데 실용적인 구성 요소가 됩니다.