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용 Model Context Protocol(MCP)을 구현하는 Node‑JS 서버입니다. Microsoft Graph API와 통신하며 Graph의 기능을 LLM 기반 어시스턴트(Claude Desktop, Open WebUI 등)가 호출할 수 있는 "도구" 집합으로 노출합니다. 실제로는 npx @softeria/ms-365-mcp-server로 패키지를 실행하면 서버가 간단한 JSON(또는 실험적인 TOON) 요청을 Graph 호출로 변환한 후, 동일한 경량 형식으로 Graph 응답을 반환합니다.

누가 사용할 수 있는가

LLM 기반 어시스턴트 – 사용자의 Outlook 메일, 일정, OneDrive 파일, Teams 채팅, SharePoint 사이트 등을 읽거나 작업해야 하는 경우.
엔터프라이즈 – 부여되는 OAuth 범위를 제한하면서 AI 에이전트에 Microsoft 365 기능의 통제된 하위 집합을 노출하려는 기업.
개발자 – 저수준 HTTP 코드를 직접 작성하지 않고 Graph에 대한 안정적이고 선언적인 인터페이스가 필요한 맞춤형 에이전트나 봇을 구축하는 개발자.

핵심 기능(README에 설명된 대로)

기능	설명
인증	Microsoft 인증 라이브러리(MSAL)를 사용하여 OAuth 토큰을 획득합니다. 범위는 활성화된 도구에서 자동으로 파생되지만 `--allowed‑scopes`로 좁히거나 `--extra‑scopes`로 확장할 수 있습니다.
도구 표면	300개 이상의 도구로, 각각 Graph 엔드포인트에 1:1로 매핑됩니다. 도구는 `src/endpoints.json`에 정의되어 있습니다. 개인 계정 도구(메일, 일정, OneDrive 등)는 기본적으로 활성화되며, 조직 모드 도구(Teams, SharePoint, 사용자 관리 등)는 `--org‑mode`로 활성화됩니다.
프리셋 및 동적 검색	프리셋(예: `mail`)과 정규식 기반 `--enabled‑tools`를 사용하여 도구 집합을 줄여 토큰 사용량을 줄이고 개인정보를 보호할 수 있습니다.
읽기 전용 모드	모든 쓰기 작업을 방지하여 안전한 샌드박스 배포에 유용합니다.
출력 형식	기본 JSON, 실험적 TOON(Token-Oriented Object Notation)은 균일한 목록 데이터의 토큰 수를 30‑60% 줄입니다.
범위 필터링	`--allowed‑scopes`(또는 `MS365_MCP_ALLOWED_SCOPES`)는 화이트리스트 역할을 하며, 필요한 Graph 범위가 포함되지 않은 도구는 숨겨집니다.
사용자 필드 필터링	`--user‑fields`는 반환되는 사용자 프로필 속성을 제한하여 데이터 최소화 계층을 추가합니다.
프록시 지원	`MS365_MCP_GRAPH_BASE_URL`을 설정하여 Graph 트래픽을 사용자 지정 프록시를 통해 라우팅합니다.
배포 옵션	CLI로 로컬 실행, HTTP 서버(`--http`), Docker, 또는 리버스 프록시 뒤(`--public‑url`)에서 실행할 수 있습니다. OAuth용 동적 클라이언트 등록을 지원합니다.
통합 예제	Claude Desktop, Claude Code CLI 및 Open WebUI에 대한 자세한 스니펫을 제공하여 MCP 서버를 도구 소스로 추가하는 방법을 보여줍니다.

작동 방식(높은 수준의 흐름)

서버 시작 – npx @softeria/ms-365-mcp-server (선택적으로 --org-mode, --http, --toon 플래그 포함).
인증 – MSAL이 브라우저를 열거나 OBO를 사용하여 활성화된 도구에 필요한 범위에 대한 액세스 토큰을 획득합니다.
도구 요청 – LLM 클라이언트가 도구 이름과 매개변수(예: list-mail-messages)를 지정하여 요청을 보냅니다.
서버 변환 – 서버는 endpoints.json에서 해당 Graph 엔드포인트를 조회하고, HTTP 요청을 구성하며, $select/$filter 규칙(사용자 필드 제한 포함)을 적용한 후 Microsoft Graph로 전달합니다.
응답 – Graph의 JSON은 선택적으로 프로젝션/필터링된 후 JSON 또는 TOON 형식으로 클라이언트에 반환됩니다.

필요하지 않은 경우

몇 개의 Graph 호출만 필요한 경우 SDK로 직접 작성하는 것이 더 간단할 수 있습니다.
사전 번들된 도구 이상의 완전한 Graph SDK 기능(배치, 델타 쿼리 등)이 필요한 프로젝트.
Node 20을 설치하거나 별도의 MCP 프로세스를 실행할 수 없는 환경.

빠른 시작 체크리스트

Node 20+를 설치합니다.
npx @softeria/ms-365-mcp-server를 실행합니다(직장/학교 기능에는 --org-mode 추가).
Claude Desktop 또는 Open WebUI 통합 단계에 따라 어시스턴트가 http://localhost:3000/mcp(또는 Docker로 노출된 포트)를 가리키도록 설정합니다.
--list-permissions를 사용하여 요청될 Graph 범위를 확인하고 필요한 경우 --allowed-scopes로 조정합니다.
(선택 사항) 토큰 효율적인 출력을 위해 --toon으로 TOON을 활성화합니다.

위의 모든 정보는 저장소의 README에서 직접 가져온 것입니다. 추가 기능은 추론되지 않았습니다.