Microsoft Teams API

teams-api

原生支持 AI 的 Microsoft Teams 集成——通过 Teams Chat Service REST API 读取对话、发送消息和管理成员。

专为需要与 Teams 交互的自主 AI Agent 设计：读取消息、回复他人、监控对话，并参与团队工作流。

说明

此项目由 Claude Opus 4.6 在人工指导和审核下通过 AI 生成。

开始使用

teams-api 有三种使用方式：

1. MCP 服务，用于编辑器和 AI 工具——这是大多数用户的推荐方式。
2. CLI，用于直接在终端中使用。
3. Node.js 编程库——适合高级用户，文档见本文末尾附近。

前提条件

• Node.js（v18 或更高版本）——npx 必需，而所有 MCP 和 CLI 命令都会使用它。

在编辑器中安装

最快的入门方式是点击上方的任一安装徽章，或按照下方适用于你所用编辑器的说明操作。

特定编辑器的说明

# VS Code
code --add-mcp '{"name":"teams","command":"npx","args":["-y","-p","teams-api@latest","teams-api-mcp"],"env":{"TEAMS_LOGIN":"true"}}'

# VS Code Insiders
code-insiders --add-mcp '{"name":"teams","command":"npx","args":["-y","-p","teams-api@latest","teams-api-mcp"],"env":{"TEAMS_LOGIN":"true"}}'

# VS Code
code --add-mcp '{"name":"teams","command":"npx","args":["-y","-p","teams-api@latest","teams-api-mcp"],"env":{"TEAMS_LOGIN":"true"}}'

# VS Code Insiders
code-insiders --add-mcp '{"name":"teams","command":"npx","args":["-y","-p","teams-api@latest","teams-api-mcp"],"env":{"TEAMS_LOGIN":"true"}}'

rem VS Code
code --add-mcp "{\"name\":\"teams\",\"command\":\"npx\",\"args\":[\"-y\",\"-p\",\"teams-api@latest\",\"teams-api-mcp\"],\"env\":{\"TEAMS_LOGIN\":\"true\"}}"

rem VS Code Insiders
code-insiders --add-mcp "{\"name\":\"teams\",\"command\":\"npx\",\"args\":[\"-y\",\"-p\",\"teams-api@latest\",\"teams-api-mcp\"],\"env\":{\"TEAMS_LOGIN\":\"true\"}}"

{
  "mcpServers": {
    "teams": {
      "command": "npx",
      "args": ["-y", "-p", "teams-api@latest", "teams-api-mcp"],
      "env": {
        "TEAMS_LOGIN": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "teams": {
      "command": "npx",
      "args": ["-y", "-p", "teams-api@latest", "teams-api-mcp"],
      "env": {
        "TEAMS_LOGIN": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "teams": {
      "command": "npx",
      "args": ["-y", "-p", "teams-api@latest", "teams-api-mcp"],
      "env": {
        "TEAMS_LOGIN": "true"
      }
    }
  }
}

claude mcp add teams -- npx -y -p teams-api@latest teams-api-mcp

{
  "mcpServers": {
    "teams": {
      "command": "npx",
      "args": ["-y", "-p", "teams-api@latest", "teams-api-mcp"],
      "env": {
        "TEAMS_LOGIN": "true"
      }
    }
  }
}

提示

在 macOS 上使用 FIDO2 通行密钥时，将 TEAMS_LOGIN 替换为 TEAMS_AUTO，即可实现完全无人值守的身份验证。详情请参阅身份验证。

命令行工具

你也可以直接使用命令行工具，无需安装任何内容：

npx -y -p teams-api@latest teams-api auth --login
npx -y -p teams-api@latest teams-api list-conversations --login --limit 20

如果经常使用命令行工具，也可以选择全局安装：

npm install -g teams-api
teams-api auth --login

Agent 技能

兼容的编码 Agent 可以安装可选的 teams-api 技能，了解何时以及如何使用命令行工具或 SDK：

npx -y skills add Maxim-Mazurok/teams-api --skill teams-api

安装程序会检测受支持的 Agent，并询问是否要为当前项目或全局安装该技能。安装后，Agent 会在处理相关 Teams 任务时自动加载它。

高级主题

手动使用令牌、调试会话身份验证，以及以编程方式使用 Node.js 的内容将在本 README 后续部分介绍。

平台支持

说明

**Windows Defender 误报：**此软件包的旧版本使用内联 PowerShell 调用 Windows DPAPI，这种模式会被 Windows Defender 标记为类似勒索软件的行为。现已改用 keytar 通过原生 Windows Credential Manager 存储。如果你在旧版本上遇到问题，请升级并重新运行 teams-api auth --login。详情请参阅 SECURITY.md。

身份验证

大多数用户无需手动管理令牌。

如果你使用交互式登录、自动登录或 Chrome 调试会话，teams-api 会自动从 Teams 网页流量中捕获完整的令牌包。其中包括基础 skypeToken，以及用于解析个人资料和可靠搜索人员、聊天和频道的额外 bearer 令牌。

这些流程还会根据拦截到的请求 URL 自动检测 Teams 聊天区域，因此大多数用户无需设置 --region 或 TEAMS_REGION。

在 macOS 上，如果你已设置平台身份验证器 / FIDO2 通行密钥，请优先使用自动登录。在其他平台上，请使用交互式登录。

直接使用令牌属于高级 / 手动方式。

自动登录（仅限 macOS）

需要运行 macOS、配备平台身份验证器（例如 Intune Company Portal），并已注册 FIDO2 通行密钥。完全无人值守——不会显示浏览器窗口。

交互式登录（Windows / Linux 推荐）

最简单的跨平台选项。系统会打开浏览器窗口，你可以使用组织支持的任意方式登录（密码、MFA、通行密钥等），然后自动捕获令牌：

teams-api auth --login

也可以预先填入你的电子邮件地址：

teams-api auth --login --email [email protected]

说明

如果有已安装的浏览器，交互式登录会优先使用 Edge 或 Chrome；否则会回退到 Playwright 自带的 Chromium。

高级／手动方法

调试会话 — 使用 --remote-debugging-port=9222 启动 Chrome，导航到 Teams 并登录，然后运行：

teams-api auth --debug-port 9222

直接令牌 — 仅限高级／手动使用。从浏览器 DevTools（Network 标签页）中提取 x-skypetoken，并直接传入：

teams-api list-conversations --token "<paste-token-here>" --region emea

如果希望在直接令牌路径下可靠地查找人员／聊天／频道并解析个人资料，请同时传入从 Teams 请求中捕获的额外 bearer 令牌：

teams-api find-people \
  --token "<paste-skype-token-here>" \
  --bearer-token "<paste-api-spaces-skype-bearer-token-here>" \
  --substrate-token "<paste-substrate-bearer-token-here>" \
  --region emea \
  --query "Jane Doe"

提示

如果使用 --login、--auto、TEAMS_LOGIN 或 TEAMS_AUTO，请跳过本节。这些模式会自动捕获完整的令牌包。

提示

直接令牌模式仍需要明确指定区域。请参阅下文的 API 区域。

CLI

无需安装时的首选方式：

npx -y -p teams-api@latest teams-api <command> [options]

频繁使用时，可选择全局安装：

npm install -g teams-api
teams-api <command> [options]

以下示例使用 teams-api 以便阅读。如果不进行全局安装，请将其替换为 npx -y -p teams-api@latest teams-api。

身份验证标志（所有命令均可用）

示例

# Acquire a token (interactive — all platforms)
teams-api auth --login

# Acquire a token (headed auto-login — macOS with FIDO2)
teams-api auth --auto --email [email protected]

# Acquire a token (headless auto-login — explicit opt-in)
teams-api auth --auto --headless --email [email protected]

# List conversations
teams-api list-conversations --login --limit 20 --format detailed

# Find a conversation by topic
teams-api find-conversation --auto --email [email protected] --query "Design Review"

# Find a 1:1 chat by person name
teams-api find-one-on-one --auto --email [email protected] --person-name "Jane Doe"

# Find people, including office location when profile enrichment is available
teams-api find-people --auto --email [email protected] --query "Jane Doe"

# Get profiles for MRIs returned by people search or member listing
teams-api get-profiles --auto --email [email protected] \
  --user-identifiers "8:orgid:00000000-0000-0000-0000-000000000000"

# Read messages (by topic name, person name, or direct ID)
teams-api get-messages --auto --email [email protected] --chat "Design Review"
teams-api get-messages --auto --email [email protected] --to "Jane Doe" --max-pages 5
teams-api get-messages --auto --email [email protected] --conversation-id "19:[email protected]" --format detailed

# Newest-first order (API returns newest-first; default is oldest-first/chronological)
teams-api get-messages --auto --email [email protected] --chat "General" --order newest-first

# Send a message
teams-api send-message --auto --email [email protected] --to "Jane Doe" --content "Hello!"
teams-api send-message --auto --email [email protected] --chat "Design Review" --content "Status update"

# List members
teams-api get-members --auto --email [email protected] --chat "Design Review"

# Get current user info
teams-api whoami --auto --email [email protected]

# Export messages to a file (default format: concise)
teams-api get-messages --auto --email [email protected] --chat "General" --output exports/general.md

# Export as JSON to a file
teams-api get-messages --auto --email [email protected] --chat "General" --format detailed --output exports/general.json

搜索消息

无需打开对话、发送消息或将消息标记为已读，即可搜索可访问的 Teams 聊天和频道帖子/回复中已编入索引的消息内容：

teams-api search-messages --login --query "release" --message-type channel

teams-api search-messages --query "*" --from [email protected] \
  --sent-after 2026-10-01 --sent-before 2026-10-26 \
  --page-size 25 --offset 0 --format detailed

选项：--query（必需；* 表示仅按筛选条件搜索）、--from（发送者邮箱）、--message-type（all、chat 或 channel）、--conversation-id、--sent-after、--sent-before、--page-size（1-100，默认值为 25）和 --offset（默认值为 0）。日期范围包含边界日期，格式为 YYYY-MM-DD。高级查询语法会传递给 Teams 搜索服务；结构化筛选条件会与其组合使用。

每次调用返回一页结果：messages、近似的 total、hasMore，以及有后续页面时的 nextOffset。将 nextOffset 作为下一次调用的 offset，并保留相同的查询和筛选条件。结果包含消息预览而非完整正文、发送者详情、对话/消息 ID、回复的父消息 ID，以及 Teams 永久链接。使用 get-messages 可完整获取已知消息或线程。

结果元数据为可选项：缺失值在 SDK 中保持为 undefined，并会从 JSON 中省略；显式空字符串则会保留。只有同时存在对话 ID 和消息 ID 时才提供永久链接。近似的 total 是服务器各结果集总数之和，未跨结果集去重；它不是唯一消息的数量。

import { TeamsClient } from "teams-api";

const client = await TeamsClient.connect({ email: "[email protected]" });
const page = await client.searchMessages({
  query: "release",
  messageType: "channel",
  from: "[email protected]",
  pageSize: 25,
});

MCP 通过 teams_search_messages 提供相同操作，参数采用驼峰命名，例如 messageType、sentAfter 和 pageSize。

消息搜索需要 Substrate bearer token。登录捕获流程会尝试执行中性的只读搜索，以防重新加载流量中未能获取该令牌。对于较早缓存的凭据，使用 --login 运行命令以捕获新的凭据包。如果浏览器搜索不可用或被阻止，消息搜索会报告身份验证错误，而不会返回空结果。使用直接令牌的用户必须提供 --substrate-token 或 TEAMS_SUBSTRATE_TOKEN。

搜索范围受已登录用户的权限、搜索索引和保留策略限制。未找到匹配项并不能证明消息不存在。HTTP 失败、无效查询和不完整的搜索响应都会作为错误报告，而不是作为空结果。

MCP 服务

MCP 服务通过 stdio 传输，将 Teams 操作作为供 AI Agent 使用的工具公开。有关针对编辑器的具体设置，请参阅入门。

高级：直接令牌配置

仅当你已通过其他流程获得令牌，或需要完全避免基于浏览器的身份验证时，才使用此方法：

{
  "mcpServers": {
    "teams": {
      "command": "npx",
      "args": ["-y", "-p", "teams-api@latest", "teams-api-mcp"],
      "env": {
        "TEAMS_TOKEN": "<paste-skype-token-here>",
        "TEAMS_BEARER_TOKEN": "<optional-api-spaces-skype-bearer-token>",
        "TEAMS_SUBSTRATE_TOKEN": "<optional-substrate-bearer-token>",
        "TEAMS_REGION": "emea"
      }
    }
  }
}

提示

如果你确实使用直接令牌，teams-api auth --login 会以 JSON 格式打印完整令牌对象。对于基本聊天操作，skypeToken 已足够。要可靠地搜索人员/聊天/频道并解析个人资料，还需传入 bearerToken 和 substrateToken。

环境变量

Agent 标记

当 AI Agent 代表用户发送或编辑消息时，很难分辨哪些消息由 Agent 撰写，哪些由用户本人撰写。TEAMS_AGENT_MARKER 环境变量（或 --agent-marker CLI 标志 / agentMarker MCP 参数）会自动在消息内容前添加可配置的字符串：

{
  "env": {
    "TEAMS_AGENT_MARKER": "Ⓜ", // or "🤖", "[Bot]", etc.
  },
}

设置后，每次调用 send-message 和 edit-message 时，都会在内容前添加标记和一个空格。例如，设置 TEAMS_AGENT_MARKER=Ⓜ 后，发送“Hello world”会生成“Ⓜ Hello world”。

单次调用参数的优先级高于环境变量。传入空字符串可针对特定调用禁用标记。

编辑回复保护

编辑已有回复的消息时，原始上下文可能会丢失，导致回复不再合理。TEAMS_EDIT_REPLY_GUARD 环境变量（或 --reply-guard CLI 标志 / replyGuard MCP 参数）用于控制此行为：

单次调用参数的优先级高于环境变量。

删除模式（软删除）

硬删除会永久移除消息内容，这可能会影响群聊中的可审计性和对话流程。TEAMS_DELETE_MODE 环境变量（或 --delete-mode CLI 标志 / deleteMode MCP 参数）用于控制消息的删除方式：

使用 soft 模式时，消息内容默认会替换为 ~~This message was removed by an agent~~。使用 TEAMS_DELETE_TOMBSTONE（或 --delete-tombstone / deleteTombstone）自定义墓碑文本：

{
  "env": {
    "TEAMS_DELETE_MODE": "soft",
    "TEAMS_DELETE_TOMBSTONE": "🗑️ [removed by automation]",
  },
}

单次调用的参数优先于环境变量。

审计日志

修改状态的操作（编辑和删除）可以生成结构化审计事件，用于合规和追踪。TEAMS_AUDIT_LOG 环境变量用于控制事件的写入位置：

{
  "env": {
    "TEAMS_AUDIT_LOG": "file:/var/log/teams-audit.jsonl",
  },
}

每个事件占一行 JSON，包含以下字段：

审计日志的设计原则是不产生干扰——审计流程中的错误不会影响工具执行。

受保护的对话

某些对话包含敏感信息或与合规相关的信息，意外编辑或删除可能造成危害。TEAMS_PROTECTED_CONVERSATIONS 环境变量（或 --protected-conversations CLI 标志 / protectedConversations MCP 参数）会阻止对匹配的对话执行编辑和删除操作：

{
  "env": {
    "TEAMS_PROTECTED_CONVERSATIONS": "Incident *,*compliance*,Architecture Decisions",
  },
}

多个模式以逗号分隔，并支持将 * 用作通配符（匹配任意字符）。匹配不区分大小写。当对话名称与任一模式匹配时，edit-message 和 delete-message 都会在进行任何更改之前抛出错误，消息保持不变。

单次调用的参数优先于环境变量，因此在需要时，单个工具调用可以覆盖已配置的模式。

可用工具

所有 MCP 工具都接受可选的 format 参数（concise 或 detailed）。默认格式为 concise。

工作流指南、提示和重要说明会通过 MCP 服务的 instructions 字段自动提供，无需单独的技能文件。要在 CLI 中查看相同内容，请运行 teams-api guide。

图片描述

teams_describe_image 会复用现有的 Teams AMS 图片下载支持，并将图片字节发送到兼容 OpenAI 的视觉端点。使用 TEAMS_IMAGE_DESCRIPTION_API_KEY 或 OPENAI_API_KEY 进行配置。可选覆盖项：TEAMS_IMAGE_DESCRIPTION_MODEL 和 TEAMS_IMAGE_DESCRIPTION_BASE_URL。

示例：

teams-api describe-image --chat "Project Chat" --message-id 1773736076914 --image-index 0
teams-api describe-image --ams-object-id 0-eaua-d2-877b82634f4e978692f2243d445a6650

API 区域

Teams Chat Service URL 因区域而异。基于登录和调试会话的身份验证会自动检测区域。只有在直接提供令牌或想强制覆盖时，才需要设置 --region 或 TEAMS_REGION：

已知限制

• 远程 AI 主机（例如 Claude.ai）不支持文件附件。MCP 服务在你的计算机本地运行，因此 --file / --image 路径必须存在于本地文件系统中。云托管的 AI 客户端运行于隔离容器中，无法访问本地路径。请使用本地 MCP 客户端（Claude Desktop、Cursor、VS Code）或 CLI 添加文件附件。
• 令牌有效期约为 24 小时。过期后，必须重新获取。
• Teams Chat Service REST API 未公开文档，且可能随时变更，恕不另行通知。
• FIDO2 自动登录不会被自动选用。使用 --auto 或 TEAMS_AUTO=true 启用；仅在需要无人值守的浏览器身份验证时，才添加 --headless 或 TEAMS_HEADLESS=true。
• 自动登录需要 macOS、系统 Chrome、平台身份验证器和 FIDO2 密钥。其他平台请改用交互式登录（--login）。
• 成员 API 会为 1:1 聊天参与者返回空显示名称。使用 findOneOnOneConversation() 从消息历史记录中解析名称。
• 表情回应者的身份信息来自消息负载中的 emotions 字段。解析时会处理 JSON 字符串和数组这两种格式。

编程式 API

这是面向高级用户的集成方式。大多数用户应从 MCP 或 CLI 开始。

在项目中安装软件包：

npm install teams-api

示例：

import { TeamsClient } from "teams-api";

// Interactive login — opens a browser, you log in manually (all platforms)
const client = await TeamsClient.fromInteractiveLogin();

// Or auto-login via platform authenticator (macOS + FIDO2 passkey)
const autoClient = await TeamsClient.fromAutoLogin({
  email: "[email protected]",
});

// Advanced/manual: create a client from previously captured tokens
const manualClient = TeamsClient.fromToken("skype-token-here", "emea");

const restoredClient = TeamsClient.fromToken(client.getToken());

const conversations = await client.listConversations();
const messages = await client.getMessages(conversations[0].id, {
  maxPages: 5,
  onProgress: (count) => console.log(`Fetched ${count} messages`),
});

await client.sendMessage(conversations[0].id, "Hello from the API!");

const oneOnOne = await client.findOneOnOneConversation("Jane Doe");
const members = await client.getMembers(conversations[0].id);
const profiles = await client.getProfiles(members.map((member) => member.id));
console.log(profiles.map((profile) => profile.userLocation));

TeamsClient.fromToken(tokenBundle) 接受由 getToken() 返回的完整 TeamsToken，其中包括没有 Skype 令牌的账户所需的 chatBearerToken。字符串形式接受 Skype 令牌和区域。

对话分页

listConversations() 返回一页内容，并默认补全未命名聊天的名称。SDK 使用者可以传入 { enrichNames: false }，以避免查询成员和个人资料。CLI 和 MCP 的行为及选项保持不变。

如需完整、轻量地枚举对话，请使用 listConversationsPage()：

let backwardLink: string | undefined;
do {
  const page = await client.listConversationsPage({
    pageSize: 500,
    enrichNames: false,
    backwardLink,
  });
  for (const conversation of page.conversations) {
    console.log(
      conversation.id,
      conversation.version,
      conversation.lastMessageTime,
    );
  }
  backwardLink = page.backwardLink ?? undefined;
} while (backwardLink);

即使某一页内容较少，或在过滤系统流后变为空，也要持续跟进 backwardLink，直到其值为 null。后续请求 URL 必须使用当前的 Chat Service 源站。两个 SDK 方法默认都启用名称补全。

使用 getMessages(id, { since })，可在达到创建时间截止点时停止消息分页。这不是编辑／删除增量数据流；检查点存储和协调策略由应用程序负责。

贡献

请参阅 CONTRIBUTING.md，了解开发环境设置、架构和实现说明。

许可证

MIT