teams-api
AI-native Microsoft Teams integration — read conversations, send messages, and manage members via the Teams Chat Service REST API.
Designed for autonomous AI agents that need to interact with Teams: read messages, reply to people, monitor conversations, and participate in team workflows.
[!NOTE] This project was AI-generated using Claude Opus 4.6 with human guidance and review.
Getting Started
teams-api can be used in three ways:
- MCP server for editors and AI tools — the recommended path for most users.
- CLI for direct terminal use.
- Programmatic Node.js library — advanced, documented near the end.
Prerequisites
- Node.js (v18 or later) — required for
npx, which all MCP and CLI commands use.
Install in your editor
The quickest way to get started is to click one of the install badges above, or follow the instructions for your editor below.
Editor-specific instructions
Option 1 — One-click install:
Option 2 — CLI:
macOS / Linux:
# 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"}}'
Windows (PowerShell):
# 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"}}'
Windows (CMD):
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\"}}"
Option 3 — Manual config:
Add to your VS Code MCP config (.vscode/mcp.json or User Settings):
{
"mcpServers": {
"teams": {
"command": "npx",
"args": ["-y", "-p", "teams-api@latest", "teams-api-mcp"],
"env": {
"TEAMS_LOGIN": "true"
}
}
}
}
Or add to ~/.cursor/mcp.json:
{
"mcpServers": {
"teams": {
"command": "npx",
"args": ["-y", "-p", "teams-api@latest", "teams-api-mcp"],
"env": {
"TEAMS_LOGIN": "true"
}
}
}
}
Add to claude_desktop_config.json (how to find it):
{
"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
Then set the environment variable TEAMS_LOGIN=true in your shell before starting Claude Code. The server will ask for your email interactively on first use.
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"teams": {
"command": "npx",
"args": ["-y", "-p", "teams-api@latest", "teams-api-mcp"],
"env": {
"TEAMS_LOGIN": "true"
}
}
}
}
[!TIP] On macOS with a FIDO2 passkey, replace
TEAMS_LOGINwithTEAMS_AUTOfor fully unattended auth. See Authentication for details.
CLI
You can also use the CLI directly without installing anything:
npx -y -p teams-api@latest teams-api auth --login
npx -y -p teams-api@latest teams-api list-conversations --login --limit 20
If you use the CLI often, a global install is optional:
npm install -g teams-api
teams-api auth --login
Agent skill
Compatible coding agents can install the optional teams-api skill to learn when and how to use the CLI or SDK:
npx -y skills add Maxim-Mazurok/teams-api --skill teams-api
The installer detects supported agents and asks whether to install the skill for the current project or globally. Once installed, the agent loads it automatically for relevant Teams tasks.
Advanced Topics
Manual token usage, debug-session auth, and programmatic Node.js usage are covered later in this README.
Platform support
[!NOTE] Windows Defender false positive: Older versions of this package used inline PowerShell to call the Windows DPAPI — a pattern that Windows Defender flags as ransomware-like behavior. This has been replaced with native Windows Credential Manager storage via keytar. If you hit issues on an older version, upgrade and re-run
teams-api auth --login. See SECURITY.md for details.
Authentication
Most users do not need to manage tokens manually.
If you use interactive login, auto-login, or a Chrome debug session, teams-api captures the full token bundle automatically from Teams web traffic. That includes the base skypeToken plus the extra bearer tokens used for profile resolution and reliable people/chat/channel search.
Those flows also detect the Teams chat region automatically from the intercepted request URLs, so most users do not need to set --region or TEAMS_REGION.
On macOS, prefer auto-login when you have a platform authenticator / FIDO2 passkey set up. On other platforms, use interactive login.
Direct token usage is the advanced/manual path.
Auto-login (macOS only)
Requires macOS with a platform authenticator (e.g. Intune Company Portal) and a FIDO2 passkey enrolled. Fully unattended — no browser window appears.
Interactive login (recommended for Windows / Linux)
The easiest cross-platform option. A browser window opens, you log in with any method your organization supports (password, MFA, passkey, etc.), and the token is captured automatically:
teams-api auth --login
Optionally pre-fill your email:
teams-api auth --login --email [email protected]
[!NOTE] Interactive login prefers an installed browser (Edge or Chrome) when available, and falls back to Playwright's bundled Chromium.
Advanced / manual methods
Debug session — start Chrome with --remote-debugging-port=9222, navigate to Teams and log in, then run:
teams-api auth --debug-port 9222
Direct token — advanced/manual only. Extract x-skypetoken from browser DevTools (Network tab) and pass it directly:
teams-api list-conversations --token "<paste-token-here>" --region emea
If you want reliable people/chat/channel lookup and profile resolution on the direct-token path, also pass the extra bearer tokens captured from Teams requests:
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"
[!TIP] Skip this section if you are using
--login,--auto,TEAMS_LOGIN, orTEAMS_AUTO. Those modes capture the full token bundle automatically.
[!TIP] Direct-token mode still needs an explicit region. See API regions below.
CLI
Preferred without install:
npx -y -p teams-api@latest teams-api <command> [options]
Optional global install for frequent use:
npm install -g teams-api
teams-api <command> [options]
The examples below use teams-api for readability. If you are not installing globally, replace it with npx -y -p teams-api@latest teams-api.
Auth flags (available on all commands)
Examples
# 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
Search messages
Search indexed message content across accessible Teams chats and channel posts/replies without opening conversations, sending messages, or marking messages read:
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
Options: --query (required; * for filter-only searches), --from (sender email), --message-type (all, chat, or channel), --conversation-id, --sent-after, --sent-before, --page-size (1-100, default 25), and --offset (default 0). Date bounds are inclusive and use YYYY-MM-DD. Advanced query syntax is passed to the Teams search service; structured filters are combined with it.
Each call returns one page: messages, approximate total, hasMore, and nextOffset when another page is available. Pass nextOffset as the next call's offset, retaining the same query and filters. Results include previews rather than full message bodies, sender details, conversation/message IDs, reply parent IDs, and Teams permalinks. Use get-messages to retrieve a known message or thread in full.
Result metadata is optional: missing values remain undefined in the SDK and are omitted from JSON, while explicit empty strings are preserved. Permalinks are available only when both conversation and message IDs are present. The approximate total sums the server's result-set totals without deduplication across result sets; it is not a unique-message count.
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 exposes the same operation as teams_search_messages, with camelCase parameters such as messageType, sentAfter, and pageSize.
Message search requires a Substrate bearer token. Login capture attempts a neutral read-only search if reload traffic did not expose that token. For older cached credentials, run the command with --login to capture a fresh bundle. If browser search is unavailable or blocked, message search reports an authentication error instead of returning an empty result. Direct-token users must provide --substrate-token or TEAMS_SUBSTRATE_TOKEN.
Search is limited by the signed-in user's permissions, search indexing, and retention policies. Zero matches do not establish that no messages exist. HTTP failures, invalid queries, and incomplete search responses are reported as errors, not empty results.
MCP server
The MCP server exposes Teams operations as tools for AI agents via stdio transport. See Getting Started for editor-specific setup.
Advanced: direct token configuration
Use this only if you already have tokens from another flow or need to avoid browser-based auth entirely:
{
"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"
}
}
}
}
[!TIP] If you do use direct tokens,
teams-api auth --loginprints the full token object as JSON. For basic chat operations,skypeTokenis enough. For reliable people/chat/channel search and profile resolution, also passbearerTokenandsubstrateToken.
Environment variables
Agent marker
When an AI agent sends or edits messages on behalf of a user, it can be hard to tell which messages were composed by the agent and which by the human. The TEAMS_AGENT_MARKER environment variable (or --agent-marker CLI flag / agentMarker MCP parameter) automatically prepends a configurable string to message content:
{
"env": {
"TEAMS_AGENT_MARKER": "Ⓜ", // or "🤖", "[Bot]", etc.
},
}
When set, every send-message and edit-message call prepends the marker followed by a space to the content. For example, with TEAMS_AGENT_MARKER=Ⓜ, sending "Hello world" produces "Ⓜ Hello world".
The per-call parameter takes precedence over the environment variable. Pass an empty string to disable the marker for a specific call.
Edit reply guard
When editing a message that already has replies, the original context can be lost — replies may no longer make sense. The TEAMS_EDIT_REPLY_GUARD environment variable (or --reply-guard CLI flag / replyGuard MCP parameter) controls this:
The per-call parameter takes precedence over the environment variable.
Delete mode (soft-delete)
Hard-deleting messages removes content permanently, which can be problematic for auditability and conversation flow in group chats. The TEAMS_DELETE_MODE environment variable (or --delete-mode CLI flag / deleteMode MCP parameter) controls how message deletion is handled:
When using soft mode, the message content is replaced with ~~This message was removed by an agent~~ by default. Customize the tombstone text with TEAMS_DELETE_TOMBSTONE (or --delete-tombstone / deleteTombstone):
{
"env": {
"TEAMS_DELETE_MODE": "soft",
"TEAMS_DELETE_TOMBSTONE": "🗑️ [removed by automation]",
},
}
The per-call parameters take precedence over environment variables.
Audit logging
State-modifying actions (edit and delete) can emit structured audit events for compliance and traceability. The TEAMS_AUDIT_LOG environment variable controls where events are written:
{
"env": {
"TEAMS_AUDIT_LOG": "file:/var/log/teams-audit.jsonl",
},
}
Each event is a single JSON line with the following fields:
Audit logging is designed to be silent — errors in the audit pipeline never affect tool execution.
Protected conversations
Some conversations contain sensitive or compliance-relevant information where accidental edits or deletions could be harmful. The TEAMS_PROTECTED_CONVERSATIONS environment variable (or --protected-conversations CLI flag / protectedConversations MCP parameter) blocks edit and delete actions in matching conversations:
{
"env": {
"TEAMS_PROTECTED_CONVERSATIONS": "Incident *,*compliance*,Architecture Decisions",
},
}
Patterns are comma-separated and support * as a wildcard (matches any characters). Matching is case-insensitive. When a conversation's name matches any pattern, both edit-message and delete-message throw an error before making any changes — the message is left untouched.
The per-call parameter takes precedence over the environment variable, so individual tool invocations can override the configured patterns when needed.
Available tools
All MCP tools accept an optional format parameter (concise or detailed). Default format is concise.
Workflow guidance, tips, and important notes are served automatically via the MCP server's instructions field — no separate skill file needed. For the same content on the CLI, run teams-api guide.
Image descriptions
teams_describe_image reuses the existing Teams AMS image download support and sends the image bytes to an OpenAI-compatible vision endpoint. Configure it with TEAMS_IMAGE_DESCRIPTION_API_KEY or OPENAI_API_KEY. Optional overrides: TEAMS_IMAGE_DESCRIPTION_MODEL and TEAMS_IMAGE_DESCRIPTION_BASE_URL.
Examples:
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 regions
The Teams Chat Service URL varies by region. Login-based and debug-session auth detect it automatically. You only need to set --region or TEAMS_REGION when you are supplying tokens directly or want to force an override:
Known limitations
- File attachments are not supported from remote AI hosts (e.g. Claude.ai). The MCP server runs locally on your machine, so
--file/--imagepaths must exist on your local filesystem. Cloud-hosted AI clients run in isolated containers and cannot access local paths. Use a local MCP client (Claude Desktop, Cursor, VS Code) or the CLI for file attachments. - Token lifetime is ~24 hours. After expiry, you must re-acquire.
- The Teams Chat Service REST API is undocumented and may change without notice.
- FIDO2 auto-login is never selected automatically. Enable it with
--autoorTEAMS_AUTO=true; add--headlessorTEAMS_HEADLESS=trueonly when unattended browser auth is wanted. - Auto-login requires macOS, system Chrome, a platform authenticator, and a FIDO2 passkey. On other platforms, use interactive login (
--login) instead. - The members API returns empty display names for 1:1 chat participants. Use
findOneOnOneConversation()to resolve names from message history. - Reaction actor identities come from the
emotionsfield in message payloads. Parsing handles both JSON-string and array formats.
Programmatic API
This is the advanced integration path. Most users should start with MCP or CLI instead.
Install the package in your project:
npm install teams-api
Example:
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) accepts the complete TeamsToken returned
by getToken(), including chatBearerToken for accounts without a Skype token.
The string form accepts a Skype token and region.
Conversation pagination
listConversations() returns one page and enriches untitled chat names by
default. SDK consumers can pass { enrichNames: false } to avoid member and
profile lookups. CLI and MCP behavior and options are unchanged.
For complete, lightweight enumeration, use 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);
Follow backwardLink until it is null, even when a page is short or becomes
empty after system-stream filtering. Continuation URLs must use the current
Chat Service origin. Name enrichment defaults to enabled on both SDK methods.
Use getMessages(id, { since }) to stop message pagination at a creation-time
cutoff. This is not an edit/deletion delta feed; applications own checkpoint
storage and reconciliation policy.
Contributing
See CONTRIBUTING.md for development setup, architecture, and implementation notes.
License
MIT
