Microsoft Teams API

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:

1. MCP server for editors and AI tools — the recommended path for most users.
2. CLI for direct terminal use.
3. Programmatic Node.js library — advanced, documented near the end.

Prerequisites

• [Node.js](https://nodejs.org/) (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

VS Code / VS Code Insiders

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" } } } }

Cursor

Or add to ~/.cursor/mcp.json:

{

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

Claude Desktop

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 Code

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.

Windsurf

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_LOGIN with TEAMS_AUTO for 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 you@example.com

[!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 " " \ --bearer-token " " \ --substrate-token " " \ --region emea \ --query "Jane Doe"

[!TIP]

Skip this section if you are using --login, --auto, TEAMS_LOGIN, or TEAMS_AUTO. Those modes captur