mcp-teams

A safe-by-default Model Context Protocol server for Microsoft Teams, over Microsoft Graph. It lets an agent read and operate Teams — list joined teams, channels and members, read channel messages and threaded replies, read 1:1/group chats and their messages, and (in higher modes) post to channels, reply in threads, send chat messages, and soft-delete a message.

Browser sign-in: on first run it opens your browser to the Microsoft sign-in page, then caches the token and refreshes it silently — the server never sees your password.

Part of the dockndevai MCP server suite — one governance model across all of them.

What it gives an agent

The server starts read-only (see Safe by default); higher-capability tools are only registered when you raise the mode.

Related MCP server: teams-mcp-server

Install

npx -y @dockndevai/mcp-teams

You need an Entra (Azure AD) app registration. For the default browser sign-in, register a public client and add the redirect URI http://localhost (platform: Mobile and desktop applications), then use its Application (client) ID as TEAMS_CLIENT_ID. Grant delegated Team.ReadBasic.All, Channel.ReadBasic.All, ChannelMessage.Read.All (and ChannelMessage.Send / Chat.ReadWrite to post). No client secret is needed for interactive use.

Configure

{
  "mcpServers": {
    "teams": {
      "command": "npx",
      "args": ["-y", "@dockndevai/mcp-teams"],
      "env": {
        "TEAMS_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "TEAMS_TENANT_ID": "common",
        "TEAMS_MODE": "read-only"
      }
    }
  }
}

On first use the server opens your browser to sign in and caches the token at ~/.mcp-teams/token.json (0600); later runs refresh silently.

See docs/CLIENTS.md for Claude Code / Cursor / Codex / VS Code / Windsurf snippets, and .env.example for every supported variable.

Authentication

Auth mode is chosen automatically (override with TEAMS_AUTH):

• interactive (default) — only TEAMS_CLIENT_ID set. Authorization-code + PKCE with a loopback redirect: the browser opens, you approve once, and the access + refresh token are cached on disk. Most Teams messaging APIs are delegated-only, so this is the primary mode. The server never handles your password.

• client-credentials (app-only) — TEAMS_CLIENT_SECRET present; the server fetches an app token itself. Note that several Teams message APIs are not available to app-only tokens without protected-API approval from Microsoft.

• token — TEAMS_TOKEN set to a pre-obtained Graph bearer token. You manage its lifetime.

Safe by default

The access model is enforced by src/security.ts — defence in depth on top of the Graph token's own scopes/roles:

• TEAMS_MODE — read-only (default) → read-write → admin. A tool is registered only if the mode allows its capability. Read-only exposes the 9 read tools; posting needs read-write; deletes need admin.

• TEAMS_ALLOW_SEND — posting a message is visible to others and can't be silently un-posted, so on top of read-write it also requires this flag.

• TEAMS_ALLOW_DELETE — deletes require this flag on top of admin mode. Deletes are soft-deletes (recoverable), and only your own messages.

• TEAMS_TEAM_ALLOWLIST / TEAMS_PROTECTED_TEAMS — confine which teams can be posted to / moderated; mark teams that may be read but never posted to.

• Interactive confirmation — when the client supports MCP elicitation, posting (send_channel_message / reply_channel_message / send_chat_message) and delete_channel_message pause and ask the human to approve before running. The prompt shows the tool, the exact (secret-redacted) arguments and a fingerprint of them; the team, channel and message length are listed separately so they stay visible when a long message is truncated in the arguments dump (the dump is cut at 1500 characters). delete_channel_message also pins the message's version (team + channel + message id with Graph's etag, lastModifiedDateTime and deletedDateTime) across the prompt and is refused if it changed. A prompt nobody answers is a refusal. Clients that can't elicit fall back to the TEAMS_ALLOW_SEND / TEAMS_ALLOW_DELETE gates.

• TEAMS_REQUIRE_HUMAN_APPROVAL — when true (default false), these operations are refused if the client cannot elicit, instead of falling back to the TEAMS_ALLOW_* gates alone.

• TEAMS_DRY_RUN — validate and log writes without executing them.

• TEAMS_AUDIT_LOG — a JSON audit line per guarded operation, on stderr (default on).

See SECURITY.md.

Developing

npm install
npm run build
# introspect the tool list without signing in (uses a fake token, no network):
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | TEAMS_TOKEN=x node dist/index.js
npm test

Licence

MIT