Teams Mcp

Teams MCP

Microsoft Graph API とシームレスに連携する Model Context Protocol（MCP）サーバーです。AI アシスタントが Microsoft Teams、ユーザー、チャット、ファイル、組織データを操作できるようにします。

📦 インストール

Cursor／Claude／VS Code でこの MCP サーバーを使用するには、次の設定を追加します。

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

🚀 機能

🔐 認証

• 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：Markdown の書式設定（太字、斜体、リスト、リンク、コードなど）をサニタイズ済み HTML に変換します

format を markdown に設定すると、メッセージの内容は安全な Markdown パーサーを使用して HTML に変換され、Teams に送信する前に危険性のあるコンテンツが取り除かれるようサニタイズされます。

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 のサニタイズ：すべての Markdown コンテンツは HTML に変換され、危険性のある要素（スクリプト、イベントハンドラーなど）が取り除かれるようサニタイズされます
• 許可されるタグ：安全な HTML タグ（p、strong、em、a、ul、ol、li、h1-h6、code、pre など）のみが許可されます
• 安全な属性：安全な属性のみが許可されます
• XSS の防止：クロスサイトスクリプティング攻撃を防ぐため、コンテンツは自動的にサニタイズされます

サポートされる Markdown 機能

• テキストの書式設定：太字（**text**）、斜体（_text_）、取り消し線（~~text~~）
• リンク：[text](url)
• リスト：箇条書き（- item）と番号付きリスト（1. item）
• コード：インラインの `code` とフェンス付きコードブロック
• 見出し：# H1 から ###### H6 まで
• 引用：> quoted text
• 表：GitHub Flavored Markdown の表

LLM に適したコンテンツ形式

Microsoft Graph API から取得したメッセージは、Teams 固有のタグを含む生の HTML として返されます。このコンテンツを AI アシスタントがより扱いやすくするため、次のツールは HTML から Markdown への自動変換をサポートしています。

• get_chat_messages
• get_channel_messages
• get_channel_message_replies
• search_messages
• get_my_mentions

コンテンツ形式のオプション

メッセージコンテンツの返却形式を制御するには、contentFormat パラメーターを使用します。

• markdown（デフォルト）：LLM での利用に最適化された、読みやすい Markdown に Teams の HTML を変換します
• raw：Microsoft Graph API からの元の HTML を返します

変換される内容

HTML 要素	Markdown の出力
<at id="0">Name</at>（Teams のメンション）	@Name（複数語の名前はメンションのメタデータを使用して結合されます）
<strong>text</strong>	**text**
<em>text</em>	*text*
<code>text</code>	`text`
<a href="url">text</a>	[text](url)
<ul><li>item</li></ul>	- item
<table>...</table>	GFM Markdown の表
<attachment id="...">	{attachment:id}
<systemEventMessage/>	(削除されます)
<hr>	---
&nbsp;、&amp; など	プレーン文字にデコードされます

添付ファイルのメタデータ

ファイル添付やインライン画像を含むメッセージのレスポンスには、各添付ファイルのメタデータ（id、name、contentType、contentUrl、thumbnailUrl）を含む attachments 配列があります。Markdown コンテンツ内のインライン {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 アクセストークンを使用します
• TEAMS_MCP_CLIENT_ID=<guid> - デフォルトの Microsoft Graph CLI アプリではなく、独自の Azure AD アプリ登録で認証します
• TEAMS_MCP_TENANT_ID=<guid-or-domain> - 特定のテナントに認証機関を固定します（例：contoso.onmicrosoft.com）。シングルテナントのアプリ登録で必要です
• TEAMS_MCP_SCOPES="User.Read Chat.ReadWrite" - 認証時に要求するアクセス許可スコープを上書きします（カンマまたはスペース区切り）

独自の Azure AD アプリ登録を使用する

デフォルトでは、サーバーは Microsoft のパブリック Graph CLI アプリを通じて認証します。独自のアプリ登録を使用するには（たとえば、テナントでそれが必要な場合）：

1. App registrations で、Authentication → Allow public client flows を Yes に設定します
2. 必要な Microsoft Graph の Delegated アクセス許可を追加します（上記のリストを参照）
3. テナントを指定してアプリで認証します：

TEAMS_MCP_CLIENT_ID=<your-app-id> \
TEAMS_MCP_TENANT_ID=<your-tenant-id> \
npx @floriscornel/teams-mcp@latest authenticate

同じ環境変数を MCP サーバープロセスにも設定し、同じアプリ ID でトークンを更新できるようにします。

管理者の同意に関するトラブルシューティング

多くの Teams のアクセス許可（Team.ReadBasic.All、ChannelMessage.*、Chat.ReadWrite、Files.ReadWrite.All）には管理者の同意が必要です。サインイン時に "Need admin approval" と表示される場合は、管理者が一度アプリに同意を付与する必要があります。Enterprise applications → Permissions → Grant admin consent から行うか、以下を開いてください：

https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent?client_id=<app-id>&scope=<space-separated scopes>&redirect_uri=<registered-redirect-uri>

管理者の同意が付与されると、authenticate はプロンプトなしで完了します。アプリ登録に構成されていないスコープを要求すると、常に管理者の承認を求められます。アプリの API permissions リストに、要求するすべてのスコープが含まれていることを確認してください。

読み取り専用モード

サーバーは読み取り専用モードに対応しており、すべての書き込み操作（メッセージの送信、チャットの作成、ファイルのアップロード、メッセージの編集・削除）が無効になり、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

読み取り専用モードで無効になる書き込みツール（15 個）： send_channel_message、reply_to_channel_message、update_channel_message、delete_channel_message、send_file_to_channel、send_chat_message、create_chat、add_chat_member、update_chat_message、delete_chat_message、send_file_to_chat、set_channel_message_reaction、set_chat_message_reaction、unset_channel_message_reaction、unset_chat_message_reaction

利用可能な MCP ツール

認証

• auth_status - 現在の認証状態を確認します

ユーザー操作

• get_current_user - 認証済みユーザーの情報を取得します
• search_users - 名前またはメールアドレスでユーザーを検索します
• get_user - ID またはメールアドレスでユーザーの詳細情報を取得します

Teams 操作

• list_teams - ユーザーが参加しているチームを一覧表示します
• list_channels - 指定したチームのチャネルを一覧表示します
• get_channel_messages - 添付ファイルの概要とコンテンツ形式の選択を含め、チームチャネルのメッセージを取得します
• get_channel_message_replies - 特定のチャネルメッセージへの返信を取得します
• send_channel_message - メンション、重要度、画像添付を指定して、チームチャネルにメッセージを送信します
• reply_to_channel_message - 既存のチャネルメッセージに返信します
• update_channel_message - 以前に送信したチャネルメッセージまたは返信を編集します
• delete_channel_message - チャネルメッセージまたは返信を論理削除します
• set_channel_message_reaction - チャネルメッセージにリアクションを追加します
• unset_channel_message_reaction - チャネルメッセージからリアクションを削除します
• list_team_members - 指定したチームのメンバーを一覧表示します
• search_users_for_mentions - メッセージ内で @メンションするチームメンバーを検索します
• send_file_to_channel - ローカルファイルをアップロードし、チャネルへのメッセージとして送信します

チャット操作

• list_chats - ユーザーのチャット（1 対 1 およびグループ）を一覧表示します
• get_chat_messages - ページネーション、フィルター、並べ替え、fetchAll を指定して、特定のチャットのメッセージを取得します
• send_chat_message - チャットにメッセージを送信します
• create_chat - 1 対 1 またはグループチャットを新規作成します
• add_chat_member - 既存のグループチャットに 1 人以上のメンバーを追加します
• update_chat_message - 以前に送信したチャットメッセージを編集します
• delete_chat_message - チャットメッセージを論理削除します
• set_chat_message_reaction - チャットメッセージにリアクションを追加します
• unset_chat_message_reaction - チャットメッセージからリアクションを削除します
• send_file_to_chat - ローカルファイルをアップロードし、チャットへのメッセージとして送信します

メディア操作

• download_message_hosted_content - チャネルメッセージからホストされたコンテンツ（画像、ファイル）をダウンロードします
• download_chat_hosted_content - チャットメッセージからホストされたコンテンツ（画像、ファイル）をダウンロードします

検索操作

• search_messages - KQL 構文を使用して、すべての Teams メッセージを検索します
• get_my_mentions - 現在のユーザーにメンションしている最近のメッセージを検索します

📋 例

認証

まず、Microsoft Graph で認証します。

# Full access (default)
npx @floriscornel/teams-mcp@latest authenticate

# Read-only (reduced permission scopes)
npx @floriscornel/teams-mcp@latest authenticate --read-only

認証状態を確認します。

npx @floriscornel/teams-mcp@latest check

必要に応じてログアウトします。

npx @floriscornel/teams-mcp@latest logout

チャットのページネーションの例

{
  "chatId": "19:meeting_...",
  "limit": 100,
  "fetchAll": true,
  "orderBy": "createdDateTime",
  "descending": true,
  "contentFormat": "markdown"
}

メンションと画像を含むチャネルメッセージ

{
  "teamId": "team-id",
  "channelId": "channel-id",
  "message": "Please review **today's update**",
  "format": "markdown",
  "importance": "high",
  "mentions": [
    {
      "mention": "alex.chen",
      "userId": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "imageUrl": "https://example.com/status.png"
}

ファイルアップロードの例

{
  "chatId": "19:meeting_...",
  "filePath": "/absolute/path/to/report.pdf",
  "message": "Please review the attached report",
  "format": "markdown"
}

Cursor/Claude との連携

この MCP サーバーは、Model Context Protocol を通じて Claude/Cursor/VS Code などの AI アシスタントと連携するように設計されています。

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

🔒 セキュリティ

• すべての認証は、Microsoft の OAuth 2.0 フローまたは呼び出し元から提供された Microsoft Graph トークンを通じて処理されます
• リフレッシュトークンのサポート：キャッシュされたリフレッシュトークンを使用してアクセストークンが自動的に更新されるため、1 時間ごとに再認証する必要はありません
• トークンキャッシュはローカルの ~/.teams-mcp-token-cache.json に保存されます
• 認証メタデータはローカルの ~/.msgraph-mcp-auth.json に保存されます
• Teams に HTML を送信する前に、Markdown コンテンツをサニタイズします
• AUTH_TOKEN が https://graph.microsoft.com を対象としていることを検証します
• 機密データがログに記録されたり、公開されたりすることはありません
• Microsoft Graph API のセキュリティに関するベストプラクティスに準拠しています

📝 ライセンス

MIT License の詳細については、LICENSE ファイルを参照してください

🤝 コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. ビルド、リント、テストを実行します
5. プルリクエストを送信します

📞 サポート

問題や質問については、以下をご確認ください。

• 既存の GitHub イシューを確認します
• Microsoft Graph API のドキュメントを確認します
• 認証と権限が適切に設定されていることを確認します