Microsoft Teams MCP Server & CLI

Give AI access to Microsoft Teams easily with your standard Teams login.

No Azure setup, app registration, Graph permissions or IT support required.

Search messages and email, catch up on unread chats, read threads, send replies, retrieve meeting transcripts and more.

Why msteams-mcp?

• Do real work - search, unread chats, threads, replies, people, channels, meetings, transcripts, files, reactions, and assignments on education tenants.

• Sign in once - tokens refresh automatically and the browser stays out of routine operations.

• Secure - the assistant has only your existing Teams permissions, with encrypted session data stored locally.

• Use it anywhere - every capability works through both MCP clients and the included msteams CLI.

Related MCP server: Teams MCP

Quick start

Prerequisites

• Node.js 20+

• A Microsoft account with Teams access

• Google Chrome, Microsoft Edge, or Chromium browser installed

Configure your MCP client

Add to your MCP client configuration (e.g., Claude Desktop, Windsurf, Cursor):

{
  "mcpServers": {
    "teams": {
      "command": "npx",
      "args": ["-y", "msteams-mcp@latest"]
    }
  }
}

That is it. npx downloads and runs the latest version. Ask your assistant to call teams_login once, complete the normal Microsoft sign-in in the browser, and then start using Teams.

How it works

This server calls Microsoft's Teams services directly (Substrate, chatsvc, CSA), using the authenticated session created by the Teams web app.

1. teams_login opens a browser for your normal Microsoft sign-in.

2. The resulting OAuth tokens and session data are encrypted and cached locally.

3. Routine operations use those tokens directly, without browser automation.

4. Expiring tokens are refreshed automatically over HTTP, with headless browser SSO as a fallback.

Your access remains limited to what your Teams account can already see and do.

From Source (alternative)

If you prefer to run from a local clone:

git clone https://github.com/m0nkmaster/msteams-mcp.git
cd msteams-mcp
npm install && npm run build

Then configure your MCP client:

{
  "mcpServers": {
    "teams": {
      "command": "node",
      "args": ["/path/to/msteams-mcp/dist/index.js"]
    }
  }
}

The server uses your system's Chrome (macOS/Linux) or Edge (Windows) for authentication.

CLI

The same functionality is also available as a standalone command-line tool, msteams. This is useful when you want Teams from a shell or script instead of an MCP client.

Install it globally from npm:

npm install -g msteams-mcp

This installs two binaries: msteams-mcp (the MCP server) and msteams (the CLI wrapper). Or run it without installing:

npx -y msteams-mcp msteams status

See CLI Usage for commands, or run msteams for the command list.

Available Tools

Search & Discovery

Messaging

People & Contacts

Organisation

Reactions

Quick reactions: like, heart, laugh, surprised, sad, angry can be used directly without searching.

Calendar & Meetings

teams_get_meetings returns: subject, times, organiser, join URL, threadId for meeting chat. Use threadId with teams_get_thread to read meeting chat, or with teams_get_transcript to get the full transcript with speakers and timestamps.

Files

teams_get_shared_files returns both files (name, extension, URL, size) and links (URL, title), along with who shared each item. Works for channels, group chats, 1:1 chats, and meeting chats.

teams_download_file takes a file's webUrl from teams_get_shared_files, or an attachment's fileUrl from teams_get_assignment. It downloads through Microsoft Graph using the Teams client's own access, so no extra sign-in is needed. Files stream straight to disk, never overwrite an existing file, and are removed if the download fails part-way. Links and Microsoft Forms aren't files and can't be downloaded.

Assignments (education tenants only)

Assignments is optional. It only works on education tenants that use Teams Assignments, and its token is requested separately, on demand, so other accounts pay no extra cost. If Assignments isn't available, or its authorisation fails, only these tools return an error: the rest of Teams keeps working, and no browser or re-login is triggered.

Download attachments (Word, PowerPoint and other files) with teams_download_file. Microsoft Forms quizzes and links are returned as URLs instead.

Session

Search Operators

Both teams_search (Teams messages) and teams_search_email (emails) support native operators:

from:sarah@company.com     # Messages/emails from person
sent:2026-01-20            # From specific date
sent:>=2026-01-15          # Since date
in:project-alpha           # Messages in channel (Teams only)
subject:"budget"           # By subject (email)
"Rob Smith"                # Find @mentions (name in quotes)
hasattachment:true         # With files
is:unread                  # Unread emails (email only)
NOT from:email@co.com      # Exclude results

Combine operators: from:sarah@co.com sent:>=2026-01-18 hasattachment:true

Note: @me, from:me, to:me do NOT work. Use teams_get_me first to get your email/displayName. sent:today works, but sent:lastweek and sent:thisweek do NOT - use explicit dates or omit (results are sorted by recency).

MCP Resources

The server also exposes passive resources for context discovery:

CLI Usage

msteams exposes every tool the MCP server does - full parity, same authentication, same session files. Commands, flags and help are generated from the tool definitions, so the CLI never lags behind the server.

If you installed globally (npm install -g msteams-mcp), invoke it directly:

# The command list, one line each
msteams
msteams --version

# What one command does, and all of its flags
msteams help send_message
msteams search --help

# Check authentication status
msteams status

# Log in (opens a browser; tries silent SSO first)
msteams login
msteams login --force        # clear session and re-login

# Search messages
msteams search "meeting notes"
msteams search "project" --from 0 --size 50

# Search emails
msteams email "from:sarah@company.com"

# Send a message (default: your own self-chat, 48:notes)
msteams send "Hello from Teams MCP!"
msteams send "Message" --to "conversation-id"

# People, contacts, favourites, activity, unread
msteams people "john smith"
msteams favorites
msteams activity
msteams unread

# Machine-readable output, on stdout, for scripts
msteams search "query" --json | jq '.results[0].conversationId'

Command form: msteams <command> [value] [--flag value].

• Commands are the tool names without the teams_/get_ prefix (search, send_message, thread, meetings). Any unambiguous abbreviation works, so send reaches send_message; the full tool name always works too.

• Flags are the tool's own parameters, in camelCase (--conversationId, --threadRootId, --fromUrl). A few short aliases exist where they read better: --to, --msg, --reply, --user, --force. Booleans work bare (--markRead) or with a value (--markRead false). Unknown flags are rejected with the list of valid ones.

• The first bare value goes to the command's main parameter: msteams search "query" is --query "query".

• Output goes to stdout, diagnostics to stderr, so pipes and redirects behave. Colour and emoji appear only on a terminal, and NO_COLOR turns them off.

• Exit codes: 0 success, 1 the tool failed, 2 the command was malformed.

• --json prints the tool's JSON payload, ready for jq.

From a repo clone

If you're working from source, the same CLI is wired to npm run cli (runs via tsx, no build needed):

npm run cli                          # command list
npm run cli -- search "your query"
npm run cli -- status
npm run cli -- send "Hi" --to "conversation-id"

Limitations

• Login required - Run teams_login to authenticate (opens browser)

• Token expiry - Tokens expire after ~1 hour; headless refresh is attempted or run teams_login again when needed

• Undocumented APIs - Uses Microsoft's internal APIs which may change without notice

• Search limitations - Full-text search only; thread replies not matching search terms won't appear (but LLM will likely use teams_get_thread for full context)

• Assignments - Education tenants only. Turn-in and undo turn-in act on your real account; handing in again records a new hand-in date that your teacher sees

Session Files

Session files are stored in a user config directory (encrypted):

• macOS/Linux: ~/.teams-mcp-server/

• Windows: %APPDATA%\teams-mcp-server\

Contents: session-state.json, token-cache.json, browser-profile/

If your session expires, call teams_login or delete the config directory.

Development

For local development:

git clone https://github.com/m0nkmaster/msteams-mcp.git
cd msteams-mcp
npm install
npm run build

Development commands:

npm run dev          # Run MCP server in dev mode
npm run build        # Compile TypeScript
npm run lint         # Run ESLint
npm test             # Run unit tests
npm run typecheck    # TypeScript type checking

For development with hot reload, configure your MCP client:

{
  "mcpServers": {
    "teams": {
      "command": "npx",
      "args": ["tsx", "/path/to/msteams-mcp/src/index.ts"]
    }
  }
}

See AGENTS.md for detailed architecture and contribution guidelines.