Microsoft Teams MCP Server & CLI

Direct AI Assistant Integration, EDU Assignment Automation & Standalone CLI for Microsoft Teams

Table of Contents

• Overview

• Quick Start

  • 1. Configure in AI MCP Clients (Claude, Cursor, Windsurf, Zed)

  • 2. Standalone Terminal CLI Usage

• Architecture & Data Flow

• CLI Commands vs MCP Tools Reference

  • Authentication & Session

  • EDU Coursework & Assignments

  • Messaging & Chats

  • Search & Emails

  • Files & Meeting Transcripts

  • People & Contacts

• Step-by-Step Assignment Workflow

• Linux Dual-Boot & Native Setup Guide

  • Prerequisites & Browser Installation

  • Cloning & Local Verification

  • Environment Variables

• Windows Setup Guide

• Development & Testing

• Security & Encryption

• Troubleshooting & FAQ

• License

Related MCP server: Teams MCP

Overview

mcp-server-msteams connects Large Language Models (Claude, GPT, Gemini, DeepSeek) and command-line users directly to Microsoft Teams.

Why Choose mcp-server-msteams?

• 🚀 Zero Azure Setup: No Azure App Registrations, no IT admin consent, and no Graph API portal configuration required. Sign in using your existing standard Teams credentials.

• ⚡ Silent 1-Second HTTP Refresh: Automatically mints and refreshes MSAL OAuth tokens via fast HTTPS endpoints in the background. The browser only opens for the initial login or if session cookies completely expire.

• 🎓 First-Class EDU Assignments: Automate listing coursework, reading rubrics, downloading assignment files, attaching local submissions (.pdf, .docx, .zip), and executing turn-in / unsubmit actions.

• 🐧 Full Linux & Windows Parity: Native cross-platform engine auto-detects Google Chrome, Brave, Microsoft Edge, and Chromium across distributions without hardcoded .exe or OS paths.

• 🛡️ End-to-End Local Security: Session tokens are encrypted on disk with AES-256-GCM using machine-derived cryptographic keys. Your credentials never touch third-party servers.

• 🛠️ Dual Interface: Includes both an MCP stdio server for AI clients and the standalone msteams CLI for bash/zsh/PowerShell scripts.

Quick Start

1. Configure in AI MCP Clients

Add mcp-server-msteams to your AI client's configuration file. The client will launch the server on-demand via npx:

Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/.config/Claude/claude_desktop_config.json (Linux/macOS):

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

Cursor & Windsurf

Add to your project's .cursor/mcp.json or global MCP settings:

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

Local Clone Execution (For Local Development)

If you prefer to run from a local repository clone:

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

2. Standalone Terminal CLI Usage

You can use all features directly from your command prompt without an AI client.

Method A: Direct Execution (Fastest — If Installed Globally)

Install once from NPM:

npm install -g mcp-server-msteams

Then run commands anywhere in your terminal:

# Check session status
msteams status

# Sign in to Teams (opens browser once)
msteams login

# List active coursework
msteams assignments --status active

Method B: Running via NPX (Without Global Installation)

If you do not want to install globally, run using npx:

# Check session status
npx -y -p mcp-server-msteams msteams status

# Sign in to Teams (opens browser once)
npx -y -p mcp-server-msteams msteams login

# List active coursework
npx -y -p mcp-server-msteams msteams assignments --status active

(Note for Windows Command Prompt users: In cmd.exe, do not paste bash comment lines starting with #).

Architecture & Data Flow

1. Protocol Layer: Standard JSON-RPC 2.0 over standard I/O (MCP specification compliant).

2. Session Engine:

   • Stores session state in ~/.teams-mcp-server/ (Linux/macOS) or %APPDATA%\teams-mcp-server\ (Windows).

   • Local token database encrypted with authenticated AES-256-GCM.

   • Persistent browser profile preserves Microsoft SSO cookies, enabling silent headless re-authentication.

3. Multi-Service Cloud Gateway:

   • ChatSvc (chatsvcagg.teams.microsoft.com): Real-time messaging, channels, direct chats, reactions.

   • Substrate (substrate.office.com): Microsoft 365 natural language search, Outlook emails, people graph.

   • Assignments (assignments.edu.cloud.microsoft): Coursework data, submission deadlines, rubrics.

   • Graph API (graph.microsoft.com): OneDrive files, SharePoint document libraries, meeting transcripts.

CLI Commands vs MCP Tools Reference

The server exposes 30+ tools to AI agents via MCP, each available as a direct command in the msteams CLI:

Authentication & Session

EDU Coursework & Assignments

Messaging & Chats

Search & Emails

Files & Meeting Transcripts

People & Contacts

Step-by-Step Assignment Workflow

Here is how an AI assistant or student automates coursework using msteams:

Step 1: Check Coursework Deadlines

msteams assignments --status active

Output returns all pending homework, modules, quizzes, and due dates across your enrolled classes.

Step 2: Read Detailed Instructions & Download Resources

msteams assignment --classId "19:abc...tacx" --assignmentId "a8f3b..."

Returns teacher rubrics, point scales, and resource download URLs. Use msteams download_file to fetch reference slides or templates.

Step 3: Attach Local Submission File

# Attach file and optionally turn in immediately:
msteams attach_file \
  --classId "19:abc...tacx" \
  --assignmentId "a8f3b..." \
  --filePath "/path/to/report.pdf" \
  --turnIn

Playwright launches headless Chromium, navigates directly to the student portal, uploads the file, verifies the attachment DOM element, and triggers the Turn In button.

Step 4: Undo Turn-In or Remove Attachment (If needed)

# Undo turn-in:
msteams submission_action --action unsubmit --classId "19:abc..." --assignmentId "a8f3b..." --submissionId "sub_01..."

# Remove attachment:
msteams remove_attachment --classId "19:abc..." --assignmentId "a8f3b..." --fileName "report.pdf"

Linux Dual-Boot & Native Setup Guide

If you are using Linux (Ubuntu, Debian, Fedora, Arch, Manjaro, Pop!_OS) or testing on a dual-boot setup:

Prerequisites & Browser Installation

Ensure you have Node.js >= 20 and any Chromium-based browser installed:

1. Install Node.js 20+

# Ubuntu / Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs git

# Fedora
sudo dnf install -y nodejs git

# Arch Linux
sudo pacman -S nodejs npm git

2. Install or Use Your Default Browser

mcp-server-msteams automatically detects your system's default browser directly from your operating system settings (via xdg-settings on Linux, UserChoice registry on Windows, or AppleScript on macOS).

It coordinates with:

• Chromium-based: Google Chrome, Microsoft Edge, Brave, Opera, Vivaldi, Chromium

• Non-Chromium: Mozilla Firefox (uses dedicated browser-profile-firefox session with automated fallback to Chromium if remote debugging protocol is unavailable)

If you don't already have a browser installed on Linux, install any of the following:

# Option A: Google Chrome (Ubuntu / Debian)
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo apt install -y ./google-chrome-stable_current_amd64.deb

# Option B: Brave Browser (Ubuntu / Debian)
sudo curl -fsSLo /usr/share/keyrings/brave-browser-archive-keyring.gpg https://brave-browser-apt-release.s3.brave.com/brave-browser-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/brave-browser-archive-keyring.gpg] https://brave-browser-apt-release.s3.brave.com/ stable main" | sudo tee /etc/apt/sources.list.d/brave-browser-release.list
sudo apt update && sudo apt install -y brave-browser

# Option C: Mozilla Firefox (Ubuntu / Debian)
sudo apt install -y firefox

# Option D: Chromium (Ubuntu / Debian)
sudo apt install -y chromium-browser

# Option E: Microsoft Edge (Ubuntu / Debian)
curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
sudo install -o root -g root -m 644 microsoft.gpg /etc/apt/trusted.gpg.d/
sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/edge stable main" > /etc/apt/sources.list.d/microsoft-edge-dev.list'
sudo apt update && sudo apt install -y microsoft-edge-stable

Cloning & Local Verification

# 1. Clone repository
git clone https://github.com/kasim672/mcp-server-msteams.git
cd mcp-server-msteams

# 2. Install dependencies & build
npm install
npm run build

# 3. Run unit tests (574 tests)
npm test

# 4. Sign in to Teams (opens browser GUI)
node dist/cli.js login

# 5. Verify authentication status
node dist/cli.js status

Environment Variables

Configure optional overrides in your ~/.bashrc or ~/.zshrc:

Windows Setup Guide

1. Ensure Node.js >= 20 is installed from nodejs.org.

2. Microsoft Edge is pre-installed on Windows 10/11 and is automatically detected. Brave and Google Chrome are also supported.

3. In PowerShell or Command Prompt:

# Clone and build
git clone https://github.com/kasim672/mcp-server-msteams.git
cd mcp-server-msteams
npm install
npm run build
npm test

# Initial login
node dist\cli.js login

# Check status
node dist\cli.js status

Session data on Windows is securely stored in %APPDATA%\teams-mcp-server\.

Development & Testing

# Run all unit tests once
npm test

# Run tests in watch mode
npm run test:watch

# Run code coverage report
npm run test:coverage

# TypeScript type checking
npm run typecheck

# Code linting
npm run lint

Security & Encryption

• No Third-Party Relays: Every API request communicates directly from your machine to Microsoft's official cloud endpoints (*.microsoft.com, *.office.com).

• Encrypted Local Storage: Cached tokens and session states are encrypted with AES-256-GCM using local machine salt and hardware-derived keys.

• Owner-Only File Permissions: On Linux and macOS, the session directory is created with 0o700 (rwx------) and files with 0o600 (rw-------).

• No Credential Escalation: The server operates strictly within the permissions of your logged-in Microsoft Teams account.

Troubleshooting & FAQ

Q: Browser fails to launch on Linux with "Missing $DISPLAY"?

mcp-server-msteams automatically detects headless Linux terminal environments and switches to headless mode. For the initial login (msteams login), ensure you are running in a desktop GUI environment (GNOME, KDE, XFCE, Sway) or pass an X11 forwarding session (ssh -X).

Q: "SingletonLock" error when starting browser?

If a browser session crashed unexpectedly, Chromium may leave behind a lock file. mcp-server-msteams automatically detects and clears stale SingletonLock files older than your running process. If needed, you can delete it manually:

# Linux / macOS
rm -f ~/.teams-mcp-server/browser-profile/SingletonLock

# Windows (PowerShell)
Remove-Item -Force "$env:APPDATA\teams-mcp-server\browser-profile\SingletonLock"

Q: How do I completely reset my login session?

Delete the local configuration folder and run msteams login again:

# Linux / macOS
rm -rf ~/.teams-mcp-server

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:APPDATA\teams-mcp-server"

License

This project is licensed under the MIT License. See the LICENSE file for details.

Developed and maintained by Kasim Ghanchi (@kasim672).