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.

[<img src="https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522teams%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522-p%2522%252C%2522teams-api%2540latest%2522%252C%2522teams-api-mcp%2522%255D%252C%2522env%2522%253A%257B%2522TEAMS_LOGIN%2522%253A%2522true%2522%257D%257D)
[<img src="https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white" alt="Install in VS Code Insiders">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522teams%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522-p%2522%252C%2522teams-api%2540latest%2522%252C%2522teams-api-mcp%2522%255D%252C%2522env%2522%253A%257B%2522TEAMS_LOGIN%2522%253A%2522true%2522%257D%257D)
[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=teams&config=%7B%22name%22%3A%22teams%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22-p%22%2C%22teams-api%40latest%22%2C%22teams-api-mcp%22%5D%2C%22env%22%3A%7B%22TEAMS_LOGIN%22%3A%22true%22%7D%7D)
[![npm version](https://img.shields.io/npm/v/teams-api?style=flat-square)](https://www.npmjs.com/package/teams-api)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-teams--api-green?style=flat-square)](https://registry.modelcontextprotocol.io)

> [!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

<details>
<summary><strong>VS Code / VS Code Insiders</strong></summary>

**Option 1 — One-click install:**

[<img src="https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522teams%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522-p%2522%252C%2522teams-api%2540latest%2522%252C%2522teams-api-mcp%2522%255D%252C%2522env%2522%253A%257B%2522TEAMS_LOGIN%2522%253A%2522true%2522%257D%257D)
[<img src="https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white" alt="Install in VS Code Insiders">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522teams%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522-p%2522%252C%2522teams-api%2540latest%2522%252C%2522teams-api-mcp%2522%255D%252C%2522env%2522%253A%257B%2522TEAMS_LOGIN%2522%253A%2522true%2522%257D%257D)

**Option 2 — CLI:**

macOS / Linux:

```bash
# 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):

```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):

```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):

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

</details>

<details>
<summary><strong>Cursor</strong></summary>

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=teams&config=%7B%22name%22%3A%22teams%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22-p%22%2C%22teams-api%40latest%22%2C%22teams-api-mcp%22%5D%2C%22env%22%3A%7B%22TEAMS_LOGIN%22%3A%22true%22%7D%7D)

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

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

</details>

<details>
<summary><strong>Claude Desktop</strong></summary>

Add to `claude_desktop_config.json` ([how to find it](https://modelcontextprotocol.io/quickstart/user)):

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

</details>

<details>
<summary><strong>Claude Code</strong></summary>

```bash
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.

</details>

<details>
<summary><strong>Windsurf</strong></summary>

Add to `~/.codeium/windsurf/mcp_config.json`:

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

</details>

> [!TIP]
> On macOS with a FIDO2 passkey, replace `TEAMS_LOGIN` with `TEAMS_AUTO` for fully unattended auth. See [Authentication](#authentication) for details.

### CLI

You can also use the CLI directly without installing anything:

```bash
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:

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

### Advanced Topics

Manual token usage, debug-session auth, and programmatic Node.js usage are covered later in this README.

## Platform support

| Feature                | macOS          | Windows / Linux                   |
| ---------------------- | -------------- | --------------------------------- |
| **Interactive login**  | Full support   | Full support                      |
| **Auto-login (FIDO2)** | Full support   | Not supported                     |
| **Debug session**      | Full support   | Full support                      |
| **Direct token**       | Full support   | Full support                      |
| **Token caching**      | macOS Keychain | Windows DPAPI / Linux secret-tool |
| **CLI & MCP server**   | Full support   | Full support                      |
| **Programmatic API**   | Full support   | Full 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](https://github.com/atom/node-keytar). If you hit issues on an older version, upgrade and re-run `teams-api auth --login`. See [SECURITY.md](./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.

| Method                | Description                                                                  | Automation       | Platform |
| --------------------- | ---------------------------------------------------------------------------- | ---------------- | -------- |
| **Auto-login**        | Playwright launches system Chrome and captures the full token bundle         | Fully unattended | macOS    |
| **Interactive login** | Opens a browser window and captures skype, middle-tier, and Substrate tokens | One-time manual  | All      |
| **Debug session**     | Connects to a running Chrome instance and captures the full token bundle     | Semi-manual      | All      |
| **Direct token**      | Provide a previously