Teams Mcp

Teams MCP

一个模型上下文协议（MCP）服务，可与 Microsoft Graph API 无缝集成，让 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

💬 聊天和消息

• 一对一和群组聊天
  • 列出用户的聊天
  • 创建新的一对一或群组对话
  • 按条件筛选、排序和分页获取聊天消息历史记录
  • 通过 @odata.nextLink 分页获取所有可用消息
  • 向现有聊天发送消息
  • 编辑已发送的聊天消息
  • 软删除聊天消息

✏️ 消息管理

• 编辑和删除
  • 更新（编辑）聊天和频道中已发送的消息
  • 软删除聊天和频道中的消息（标记为已删除，但不会永久移除）
  • 只有消息发送者才能更新或删除自己的消息
  • 编辑时支持 Markdown 格式、提及和重要性级别

📎 媒体和附件

• 托管内容

  • 下载聊天和频道消息中的托管内容（图片、文件）
  • 访问对话中分享的内联图片和附件
  • 可选择将托管内容直接保存到磁盘

• 文件上传

  • 向频道和聊天上传并发送任何文件类型（PDF、DOCX、XLSX、ZIP、图片等）
  • 通过可续传上传会话支持大型文件（>4 MB）
  • 频道上传到 SharePoint，聊天上传到 OneDrive
  • 可选的消息文本、自定义文件名、格式和重要性级别

🔍 高级搜索和发现

• 消息搜索
  • 使用 Microsoft Search API 搜索所有 Teams 频道和聊天
  • 支持 KQL（关键词查询语言）语法
  • 按发送者、提及、附件、已读状态和日期范围筛选
  • 使用高级筛选选项获取近期消息
  • 查找提及当前用户的消息

富消息格式支持

以下工具支持在 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 风格的 Markdown 表格

适合大模型处理的内容格式

从 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（默认）：将 Teams HTML 转换为简洁的 Markdown，便于大模型处理
• 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; 等	解码为普通字符

附件元数据

包含文件附件或内嵌图片的消息，会在响应中包含一个 attachments 数组，其中列出每个附件的元数据（id、name、contentType、contentUrl、thumbnailUrl）。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> - 使用现有的 Microsoft Graph 访问令牌，而非 MSAL 登录
• TEAMS_MCP_CLIENT_ID=<guid> - 使用你自己的 Azure AD 应用注册进行身份验证，而非默认的 Microsoft Graph CLI 应用
• TEAMS_MCP_TENANT_ID=<guid-or-domain> - 将授权机构固定到特定租户（例如 contoso.onmicrosoft.com）；单租户应用注册必需
• TEAMS_MCP_SCOPES="User.Read Chat.ReadWrite" - 覆盖身份验证期间请求的权限范围（以逗号或空格分隔）

使用自己的 Azure AD 应用注册

默认情况下，服务通过 Microsoft 的公共 Graph CLI 应用进行身份验证。若要使用自己的应用注册（例如，租户要求使用自有应用注册时）：

1. 在 应用注册 中，将 身份验证 → 允许公共客户端流 设为 是
2. 添加所需的 Microsoft Graph 委托权限（参见上方列表）
3. 使用固定到你的租户的应用进行身份验证：

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

在 MCP 服务进程中设置相同的环境变量，使其能够使用相同的应用身份续订令牌。

管理员同意故障排除

大多数 Teams 权限（Team.ReadBasic.All、ChannelMessage.*、Chat.ReadWrite、Files.ReadWrite.All）都需要管理员同意。如果登录时显示 “需要管理员批准”，管理员必须为该应用授予一次同意 — 可通过 企业应用程序 → 权限 → 授予管理员同意，或打开：

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

授予管理员同意后，authenticate 将无需提示即可完成。请求应用注册中未配置的范围始终会触发管理员批准提示 — 请确认应用的 API 权限列表涵盖所有请求的范围。

只读模式

服务器支持只读模式，可禁用所有写入操作（发送消息、创建聊天、上传文件、编辑／删除消息），并且只请求 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 - 向现有群组聊天添加一名或多名成员
• 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 令牌处理
• 支持刷新令牌：系统会使用缓存的刷新令牌自动续期访问令牌，因此无需每小时重新进行身份验证
• 令牌缓存存储在本地 ~/.teams-mcp-token-cache.json
• 身份验证元数据存储在本地 ~/.msgraph-mcp-auth.json
• 将 HTML 内容发送到 Teams 前，会对 Markdown 内容进行清理
• 会验证 AUTH_TOKEN，确保其目标为 https://graph.microsoft.com
• 不会记录或泄露任何敏感数据
• 遵循 Microsoft Graph API 安全最佳实践

📝 许可证

MIT 许可证——详情请参阅 LICENSE 文件

🤝 参与贡献

1. Fork 此存储库
2. 创建功能分支
3. 进行更改
4. 运行构建、代码检查和测试
5. 提交拉取请求

📞 支持

如有问题或疑问：

• 查看现有的 GitHub issues
• 查阅 Microsoft Graph API 文档
• 确保已正确配置身份验证和权限