mcp-teams

Name: mcp teams
Author: dockndevai

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.

Tool	For	Needs mode
`whoami`	confirm which account is in use	read-only
`list_teams`	teams the user has joined	read-only
`list_channels`	channels in a team	read-only
`list_team_members`	members of a team	read-only
`list_channel_messages`	recent messages in a channel	read-only
`get_channel_message`	one channel message + body	read-only
`list_message_replies`	a channel message's thread	read-only
`list_chats`	the user's 1:1 / group chats	read-only
`list_chat_messages`	messages in a chat	read-only
`send_channel_message`	post to a channel	read-write + `TEAMS_ALLOW_SEND`
`reply_channel_message`	reply in a channel thread	read-write + `TEAMS_ALLOW_SEND`
`send_chat_message`	send a chat message	read-write + `TEAMS_ALLOW_SEND`
`delete_channel_message`	soft-delete your own message	admin + `TEAMS_ALLOW_DELETE`

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 and deleting pause and ask the human to approve the exact target before running; clients that can't elicit fall back to the TEAMS_ALLOW_SEND / TEAMS_ALLOW_DELETE gates.
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