Microsoft Teams API

teams-api

AI ネイティブな Microsoft Teams 統合 — Teams Chat Service REST API を介して会話を読み、メッセージを送信し、メンバーを管理できます。

Teams を操作する必要のある自律型 AI エージェント向けに設計されています。メッセージの読み取り、人への返信、会話の監視、チームのワークフローへの参加ができます。

メモ

このプロジェクトは、Claude Opus 4.6 を使用して AI が生成し、人間による指導とレビューを経ています。

はじめに

teams-api は、次の3つの方法で使用できます。

1. MCP サーバー：エディターや AI ツール向け。ほとんどのユーザーに推奨される方法です。
2. CLI：ターミナルから直接使用します。
3. プログラムから利用できる Node.js ライブラリ：上級者向け。詳しくは後半で説明します。

前提条件

• Node.js（v18 以降） — すべての MCP および CLI コマンドで使用する npx に必要です。

エディターにインストール

手早く始めるには、上のインストールバッジのいずれかをクリックするか、以下のエディター別の手順に従ってください。

エディター固有の手順

# 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 に置き換えてください。詳しくは認証をご覧ください。

CLI

何もインストールせずに、CLI を直接使用することもできます：

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

CLI を頻繁に使う場合は、グローバルインストールも可能です（任意）：

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

エージェントスキル

互換性のあるコーディングエージェントには、CLI または SDK の使用タイミングと方法を学習するための任意の teams-api スキルをインストールできます：

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

インストーラーは対応するエージェントを検出し、スキルを現在のプロジェクトまたはグローバルにインストールするかどうかを尋ねます。インストール後、エージェントは関連する 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 に加え、プロファイルの解決や、ユーザー／チャット／チャネルを確実に検索するために使われる追加のベアラートークンが含まれます。

これらのフローでは、傍受したリクエスト URL から Teams のチャットリージョンも自動的に検出されるため、ほとんどのユーザーは --region や TEAMS_REGION を設定する必要がありません。

macOS では、プラットフォーム認証器／FIDO2 パスキーを設定している場合、自動ログインを推奨します。他のプラットフォームでは、インタラクティブログインを使用してください。

直接トークンを使う方法は、上級者向けの手動操作です。

自動ログイン（macOS のみ）

プラットフォーム認証器（Intune Company Portal など）と、登録済みの FIDO2 パスキーがある macOS が必要です。完全無人で実行され、ブラウザーウィンドウは表示されません。

インタラクティブログイン（Windows／Linux に推奨）

最も簡単なクロスプラットフォーム対応の方法です。ブラウザーウィンドウが開き、組織がサポートする任意の方法（パスワード、MFA、パスキーなど）でログインすると、トークンが自動的に取得されます。

teams-api auth --login

必要に応じて、メールアドレスをあらかじめ入力できます。

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

メモ

インタラクティブログインでは、利用可能な場合、インストール済みのブラウザー（Edge または Chrome）が優先され、利用できない場合は Playwright にバンドルされた Chromium が使用されます。

高度な方法／手動での方法

デバッグセッション — Chrome を --remote-debugging-port=9222 を指定して起動し、Teams に移動してログインしてから、次を実行します。

teams-api auth --debug-port 9222

直接トークン — 高度な方法／手動での使用のみです。ブラウザーの DevTools（Network タブ）から x-skypetoken を抽出し、直接渡します。

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

直接トークンを使用する方法で、確実にユーザー／チャット／チャネルを検索し、プロフィールを解決するには、Teams のリクエストから取得した追加のベアラートークンも渡してください。

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 を使用しています。グローバルインストールをしない場合は、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 の検索サービスに渡され、構造化フィルターと組み合わせて適用されます。

各呼び出しで返されるのは 1 ページ分です。内容は messages、概算の total、hasMore、次のページがある場合は nextOffset です。次の呼び出しでは、同じクエリとフィルターを維持したまま、nextOffset を offset として渡します。結果には、メッセージ本文全体ではなくプレビュー、送信者の詳細、会話 ID／メッセージ 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 のベアラートークンが必要です。ログイン時のキャプチャでは、ページの再読み込み時の通信からトークンを取得できなかった場合、中立的な読み取り専用検索を試みます。古いキャッシュ済み認証情報を使用する場合は、コマンドに --login を指定して新しいバンドルを取得します。ブラウザー検索を利用できない場合やブロックされている場合、メッセージ検索は空の結果を返すのではなく、認証エラーを報告します。トークンを直接指定するユーザーは、--substrate-token または TEAMS_SUBSTRATE_TOKEN を指定する必要があります。

検索結果は、サインイン中のユーザーのアクセス許可、検索インデックス、保持ポリシーによって制限されます。該当結果が 0 件でも、メッセージが存在しないことを意味するとは限りません。HTTP エラー、無効なクエリ、不完全な検索応答は、空の結果ではなくエラーとして報告されます。

MCP サーバー

MCP サーバーは、stdio トランスポートを介して Teams の操作を AI エージェント向けのツールとして公開します。エディターごとの設定については、はじめにを参照してください。

上級者向け：トークンの直接設定

別の手順ですでにトークンを取得している場合、またはブラウザーベースの認証を完全に避ける必要がある場合にのみ使用してください。

{
  "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 も渡してください。

環境変数

エージェント識別子

AI エージェントがユーザーに代わってメッセージを送信または編集すると、どのメッセージがエージェントによって作成され、どのメッセージが人間によって作成されたのかを判別しにくい場合があります。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",
  },
}

各イベントは、次のフィールドを含む 1 行の 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() を使用してください。
• リアクションを行ったユーザーの ID は、メッセージペイロードの 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() は1ページ分を返し、デフォルトでタイトルのないチャット名を補完します。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