Teams MCP

AI 어시스턴트가 Microsoft Teams, 사용자, 채팅, 파일 및 조직 데이터와 상호 작용할 수 있도록 Microsoft Graph API와의 원활한 통합을 제공하는 Model Context Protocol (MCP) 서버입니다.

📦 설치

Cursor/Claude/VS Code에서 이 MCP 서버를 사용하려면 다음 구성을 추가하세요:

{
  "mcpServers": {
    "teams-mcp": {
      "command": "npx",
      "args": ["-y", "@floriscornel/teams-mcp@latest"]
    }
  }
}

Related MCP server: Meeting BaaS MCP Server

🚀 기능

🔐 인증

• Microsoft Graph를 사용한 OAuth 2.0 장치 코드 인증 흐름

• 안전한 토큰 관리, 캐시 유지 및 새로 고침 토큰 갱신

• 인증 상태 확인 및 로그아웃 지원

• 축소된 범위를 사용하는 읽기 전용 모드

• 사전 발급된 Microsoft Graph 액세스 토큰을 위한 직접적인 AUTH_TOKEN 지원

👥 사용자 관리

• 현재 사용자 정보 가져오기

• 이름 또는 이메일로 사용자 검색

• 상세 사용자 프로필 검색

• 조직 디렉터리 데이터 액세스

🏢 Microsoft Teams 통합

• 팀 관리

  • 사용자가 참여한 팀 목록

  • 팀 세부 정보 및 메타데이터 액세스

• 채널 작업

  • 팀 내 채널 목록

  • 채널 메시지 및 답글 검색

  • 팀 채널로 메시지 전송

  • 기존 채널 스레드에 답글 달기

  • 채널 메시지 및 답글 편집 및 소프트 삭제

  • 메시지 중요도 수준 지원 (normal, high, urgent)

  • URL 또는 base64 데이터를 통한 인라인 이미지 첨부 지원

• 팀 멤버

  • 팀 멤버 및 역할 목록

  • 멤버 정보 액세스

  • @mentions를 위한 사용자 검색

💬 채팅 및 메시징

• 1:1 및 그룹 채팅

  • 사용자의 채팅 목록

  • 새로운 1:1 또는 그룹 대화 생성

  • 필터링, 정렬 및 페이지 매김을 포함한 채팅 메시지 기록 검색

  • @odata.nextLink 페이지 매김을 통한 모든 사용 가능한 메시지 가져오기

  • 기존 채팅으로 메시지 전송

  • 이전에 보낸 채팅 메시지 편집

  • 채팅 메시지 소프트 삭제

✏️ 메시지 관리

• 편집 및 삭제

  • 채팅 및 채널에서 보낸 메시지 업데이트(편집)

  • 채팅 및 채널에서 메시지 소프트 삭제(영구 삭제 없이 삭제됨으로 표시)

  • 메시지 발신자만 자신의 메시지를 업데이트/삭제 가능

  • 편집 시 Markdown 서식, 멘션 및 중요도 수준 지원

📎 미디어 및 첨부 파일

• 호스팅된 콘텐츠

  • 채팅 및 채널 메시지에서 호스팅된 콘텐츠(이미지, 파일) 다운로드

  • 대화에서 공유된 인라인 이미지 및 첨부 파일 액세스

  • 호스팅된 콘텐츠를 디스크에 직접 저장하는 옵션

• 파일 업로드

  • 모든 파일 형식(PDF, DOCX, XLSX, ZIP, 이미지 등)을 채널 및 채팅으로 업로드 및 전송

  • 재개 가능한 업로드 세션을 통한 대용량 파일 지원(>4 MB)

  • 채널 업로드는 SharePoint로, 채팅 업로드는 OneDrive로 전송

  • 선택적 메시지 텍스트, 사용자 지정 파일 이름, 서식 및 중요도 수준

🔍 고급 검색 및 탐색

• 메시지 검색

  • Microsoft Search API를 사용하여 모든 Teams 채널 및 채팅 검색

  • KQL(Keyword Query Language) 구문 지원

  • 발신자, 멘션, 첨부 파일, 읽음 상태 및 날짜 범위별 필터링

  • 고급 필터링 옵션으로 최근 메시지 가져오기

  • 현재 사용자를 멘션하는 메시지 찾기

리치 메시지 서식 지원

다음 도구는 Teams 채널 및 채팅에서 리치 메시지 서식을 지원합니다:

• send_channel_message

• send_chat_message

• reply_to_channel_message

• update_channel_message

• update_chat_message

• send_file_to_channel

• send_file_to_chat

서식 옵션

format 매개변수를 지정하여 메시지 서식을 제어할 수 있습니다:

• text (기본값): 일반 텍스트

• markdown: 안전하게 처리된 HTML로 변환된 Markdown 서식(굵게, 기울임꼴, 목록, 링크, 코드 등)

format이 markdown으로 설정되면 메시지 내용은 안전한 마크다운 파서를 사용하여 HTML로 변환되고, Teams로 전송되기 전에 잠재적으로 위험한 콘텐츠를 제거하기 위해 삭제(sanitized)됩니다.

format이 지정되지 않으면 메시지는 일반 텍스트로 전송됩니다.

사용 예시

{
  "teamId": "...",
  "channelId": "...",
  "message": "**Bold text** and _italic text_\n\n- List item 1\n- List item 2\n\n[Link](https://example.com)",
  "format": "markdown",
  "importance": "high"
}

{
  "chatId": "...",
  "message": "Simple plain text message",
  "format": "text"
}

보안 기능

• HTML 삭제(Sanitization): 모든 마크다운 콘텐츠는 HTML로 변환되고 잠재적으로 위험한 요소(스크립트, 이벤트 핸들러 등)를 제거하기 위해 삭제됩니다.

• 허용된 태그: 안전한 HTML 태그만 허용됩니다(p, strong, em, a, ul, ol, li, h1-h6, code, pre 등).

• 안전한 속성: 안전한 속성만 허용됩니다.

• XSS 방지: 교차 사이트 스크립팅 공격을 방지하기 위해 콘텐츠가 자동으로 삭제됩니다.

지원되는 마크다운 기능

• 텍스트 서식: 굵게 (**text**), 기울임꼴 (_text_), 취소선 (~~text~~)

• 링크: [text](url)

• 목록: 글머리 기호 (- item) 및 번호 매기기 (1. item)

• 코드: 인라인 `code` 및 코드 블록

• 제목: # H1 ~ ###### H6

• 블록 인용: > quoted text

• 표: GitHub 스타일 마크다운 표

LLM 친화적인 콘텐츠 형식

Microsoft Graph API에서 검색된 메시지는 Teams 전용 태그가 포함된 원시 HTML로 반환됩니다. AI 어시스턴트가 이 콘텐츠를 더 쉽게 소비할 수 있도록 다음 도구는 자동 HTML-to-Markdown 변환을 지원합니다:

• get_chat_messages

• get_channel_messages

• get_channel_message_replies

• search_messages

• get_my_mentions

콘텐츠 형식 옵션

contentFormat 매개변수를 사용하여 메시지 콘텐츠가 반환되는 방식을 제어하세요:

• markdown (기본값): Teams HTML을 LLM 소비에 최적화된 깔끔한 Markdown으로 변환

• raw: Microsoft Graph API에서 원본 HTML 반환

변환 대상

첨부 파일 메타데이터

파일 첨부 파일이나 인라인 이미지가 포함된 메시지는 응답에 각 첨부 파일에 대한 메타데이터(id, name, contentType, contentUrl, thumbnailUrl)가 포함된 attachments 배열을 포함합니다. 마크다운 콘텐츠의 인라인 {attachment:id} 마커는 이 배열의 항목과 연관되어 있어 소비자가 download_message_hosted_content 또는 download_chat_hosted_content를 통해 첨부 파일을 식별하고 다운로드할 수 있습니다.

사용 예시

{
  "chatId": "19:meeting_...",
  "limit": 10,
  "contentFormat": "markdown"
}

원본 HTML을 가져오려면:

{
  "chatId": "19:meeting_...",
  "limit": 10,
  "contentFormat": "raw"
}

📦 설치

# Install dependencies
npm install

# Build the project
npm run build

# Set up authentication
npm run auth

🔧 구성

필수 조건

• Node.js 18+

• 적절한 권한이 있는 Microsoft 365 계정

• 아래 범위에 대한 Microsoft Graph 위임 권한

필수 Microsoft Graph 권한

전체 모드(기본값):

• User.Read - 사용자 프로필 읽기

• User.ReadBasic.All - 기본 사용자 정보 읽기

• Team.ReadBasic.All - 팀 정보 읽기

• Channel.ReadBasic.All - 채널 정보 읽기

• ChannelMessage.Read.All - 채널 메시지 읽기

• ChannelMessage.Send - 채널 메시지 및 답글 전송

• ChannelMessage.ReadWrite - 채널 메시지 편집 및 삭제

• Chat.Read - 채팅 메시지 읽기(읽기 전용 범위에 포함)

• Chat.ReadWrite - 채팅 생성 및 관리, 채팅 메시지 전송/편집/삭제 (Chat.Read 대체)

• TeamMember.Read.All - 팀 멤버 읽기

• Files.ReadWrite.All - 채널 및 채팅으로 파일 업로드 시 필요

읽기 전용 모드 (TEAMS_MCP_READ_ONLY=true) — 다음 범위만 요청됨:

• User.Read

• User.ReadBasic.All

• Team.ReadBasic.All

• Channel.ReadBasic.All

• ChannelMessage.Read.All

• TeamMember.Read.All

• Chat.Read

인증 모드

전체 액세스:

npx @floriscornel/teams-mcp@latest authenticate

읽기 전용 액세스:

npx @floriscornel/teams-mcp@latest authenticate --read-only

기존 Microsoft Graph JWT를 사용한 직접 토큰 주입:

{
  "mcpServers": {
    "teams-mcp": {
      "command": "npx",
      "args": ["-y", "@floriscornel/teams-mcp@latest"],
      "env": {
        "AUTH_TOKEN": "<jwt-for-https://graph.microsoft.com>"
      }
    }
  }
}

토큰 저장소

• 인증 메타데이터는 ~/.msgraph-mcp-auth.json에 로컬로 저장됩니다.

• 토큰 캐시는 ~/.teams-mcp-token-cache.json에 로컬로 저장됩니다.

🛠️ 사용법

서버 시작

# Development mode with hot reload
npm run dev

# Production mode
npm run build && node dist/index.js

# Start in read-only mode (disables all write tools)
TEAMS_MCP_READ_ONLY=true node dist/index.js

CLI 명령

npx @floriscornel/teams-mcp@latest authenticate              # Authenticate with full scopes
npx @floriscornel/teams-mcp@latest authenticate --read-only  # Authenticate with read-only scopes
npx @floriscornel/teams-mcp@latest check                     # Check authentication status
npx @floriscornel/teams-mcp@latest logout                    # Clear authentication
npx @floriscornel/teams-mcp@latest auth                      # Alias for authenticate
npx @floriscornel/teams-mcp@latest                           # Start MCP server (default)

환경 변수

• TEAMS_MCP_READ_ONLY=true - MCP 서버를 읽기 전용 모드로 시작

• AUTH_TOKEN=<jwt> - MSAL 로그인 대신 기존 Microsoft Graph 액세스 토큰 사용

읽기 전용 모드

서버는 모든 쓰기 작업(메시지 전송, 채팅 생성, 파일 업로드, 메시지 편집/삭제)을 비활성화하고 Microsoft Graph에서 읽기 권한 범위만 요청하는 읽기 전용 모드를 지원합니다.

읽기 전용 모드 활성화 방법:

• 환경 변수: TEAMS_MCP_READ_ONLY=true

• CLI 플래그: --read-only

축소된 범위로 인증:

npx @floriscornel/teams-mcp@latest authenticate --read-only

MCP 서버 구성(읽기 전용):

{
  "mcpServers": {
    "teams-mcp": {
      "command": "npx",
      "args": ["-y", "@floriscornel/teams-mcp@latest"],
      "env": {
        "TEAMS_MCP_READ_ONLY": "true"
      }
    }
  }
}

모드 전환: 읽기 전용 모드에서 전체 모드로 전환할 때 서버는 범위 불일치를 감지하고 다시 인증하라는 경고를 표시합니다:

npx @floriscornel/teams-mcp@latest authenticate

읽기 전용 도구 (16): auth_status, get_current_user, search_users, get_user, list_teams, list_channels, get_channel_messages, get_channel_message_replies, list_team_members, search_users_for_mentions, download_message_hosted_content, list_chats, get_chat_messages, download_chat_hosted_content, search_messages, get_my_mentions

읽기 전용 모드에서 비활성화된 쓰기 도구 (10): send_channel_message, reply_to_channel_message, update_channel_message, delete_channel_message, send_file_to_channel, send_chat_message, create_chat, update_chat_message, delete_chat_message, send_file_to_chat

사용 가능한 MCP 도구

인증

• auth_status - 현재 인증 상태 확인

사용자 작업

• get_current_user - 인증된 사용자 정보 가져오기

• search_users - 이름 또는 이메일로 사용자 검색

• get_user - ID 또는 이메일로 상세 사용자 정보 가져오기

팀 작업

• list_teams - 사용자가 참여한 팀 목록

• list_channels - 특정 팀의 채널 목록

• get_channel_messages - 첨부 파일 요약 및 콘텐츠 형식 선택을 포함하여 팀 채널에서 메시지 검색

• get_channel_message_replies - 특정 채널 메시지에 대한 답글 가져오기

• send_channel_message - 멘션, 중요도 및 이미지 첨부 파일을 선택적으로 포함하여 팀 채널로 메시지 전송

• reply_to_channel_message - 기존 채널 메시지에 답글 달기

• update_channel_message - 이전에 보낸 채널 메시지 또는 답글 편집

• delete_channel_message - 채널 메시지 또는 답글 소프트 삭제

• list_team_members - 특정 팀의 멤버 목록

• search_users_for_mentions - 메시지에서 @멘션할 팀 멤버 검색

• send_file_to_channel - 로컬 파일을 업로드하고 채널로 메시지 전송

채팅 작업

• list_chats - 사용자의 채팅 목록(1:1 및 그룹)

• get_chat_messages - 페이지 매김, 필터, 정렬 및 fetchAll을 사용하여 특정 채팅에서 메시지 검색

• send_chat_message - 채팅으로 메시지 전송