Skip to main content
Glama
Teams Puppeteer MCP Server

Teams Puppeteer MCP Server

by tinobruno

Teams Puppeteer MCP Server

License: MIT Node.js Model Context Protocol

A high-performance Model Context Protocol (MCP) server for Microsoft Teams chat automation, message extraction, and unread notification monitoring powered by Puppeteer.


πŸ’‘ Why This Project?

Most Microsoft Teams integrations require:

  • ❌ Enterprise Azure App Registration

  • ❌ Azure Tenant Administrator Consent

  • ❌ Paid Microsoft 365 / Graph API licenses & Bot frameworks

teams-puppeteer-mcp takes a radically simpler approach:

  • βœ… Zero Setup / No API Keys: Uses npx with zero local file path configuration.

  • βœ… Direct Web Client Automation: Interacts directly with Microsoft Teams (teams.cloud.microsoft) using your standard browser profile.

  • βœ… Persistent SSO & MFA Session: Log in once interactively with your work, school, or personal account. Your session cookies and tokens persist locally in your user profile.

  • βœ… Zero Token Overhead: Optimized specifically for LLMs. Returns clean, high-density human/LLM-readable text without nested JSON bloat.

  • βœ… Full Cross-Platform Support: Works seamlessly on Windows, macOS, and Linux.


Related MCP server: Teams MCP Server

πŸš€ Quick Setup (Zero Configuration)

You do not need to manually clone this repository or guess local file paths. You can add it directly to your MCP client using npx.

TIP

Merging with existing servers: If you already have other MCP servers configured in your client, do not overwrite the whole file! Simply insert the "teams" (or "teams-puppeteer") block into your existing "mcpServers" object.

1. Claude Desktop

Add this to your claude_desktop_config.json:

  • Windows: %APPDATA%\\Claude\\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "//": "... keep your other existing servers here ...",
    "teams": {
      "command": "npx",
      "args": [
        "-y",
        "@tinobruno/teams-puppeteer-mcp"
      ]
    }
  }
}

Note: You can also run directly from GitHub without npm: "args": ["-y", "github:tinobruno/teams-puppeteer-mcp"]


2. Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.json or via Settings β†’ Features β†’ MCP):

{
  "mcpServers": {
    "//": "... keep your other existing servers here ...",
    "teams": {
      "command": "npx",
      "args": [
        "-y",
        "@tinobruno/teams-puppeteer-mcp"
      ]
    }
  }
}

3. VS Code (Cline / Roo-Code)

In your Cline MCP settings (cline_mcp_settings.json):

{
  "mcpServers": {
    "//": "... keep your other existing servers here ...",
    "teams": {
      "command": "npx",
      "args": [
        "-y",
        "@tinobruno/teams-puppeteer-mcp"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

4. MinnieTheMoEcher

You can add it via the Web UI (under Settings β†’ MCP Servers β†’ + Add Server) or by adding this entry into your existing mcp_servers.json:

{
  "mcpServers": {
    "//": "... keep your other existing servers here ...",
    "teams-puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@tinobruno/teams-puppeteer-mcp"
      ],
      "enabled": true,
      "transport_type": "stdio"
    }
  }
}

πŸ”‘ First-Time Interactive Login

On your first run:

  1. When your AI assistant invokes a Teams tool, a browser window will launch and navigate to Microsoft Teams (https://teams.cloud.microsoft).

  2. Log in with your corporate SSO, password, and complete your Multi-Factor Authentication (MFA/2FA) prompt.

  3. Once you reach the Teams chat interface, your session is automatically saved to your local profile directory (~/.teams_puppeteer_profile on macOS/Linux, or %USERPROFILE%\\.teams_puppeteer_profile on Windows).

  4. Subsequent calls will automatically connect to your authenticated session.


πŸ› οΈ Available MCP Tools

Tool Name

Description

Parameters

get_last_message

Primary tool to read the single latest message from a contact, group, or channel. Matches partial names automatically.

chat_name (required, string)

get_last_unread_message

Scans for unread messages. If chat_name is omitted, scans across all conversations and returns a compact summary.

chat_name (optional, string)

get_last_messages

Retrieves the last N messages from a specific conversation.

chat_name (required), count (optional, number, default: 3)

list_teams_chats

Lists sidebar conversation names, unread flags, and latest activity timestamps.

limit (optional, number, default: 10)

send_teams_message

Types and dispatches a message into Teams using native keyboard input into CKEditor 5.

chat_name (required), message (required)


βš™οΈ Environment Variables (Optional)

You can customize the behavior by passing optional env variables in your MCP client config:

{
  "mcpServers": {
    "//": "... keep your other existing servers here ...",
    "teams": {
      "command": "npx",
      "args": ["-y", "@tinobruno/teams-puppeteer-mcp"],
      "env": {
        "TEAMS_HEADLESS": "true",
        "PUPPETEER_EXECUTABLE_PATH": "/usr/bin/google-chrome"
      }
    }
  }
}

Variable

Description

Default

TEAMS_HEADLESS

Set to "true" to run browser in the background after initial login.

"false"

TEAMS_PROFILE_DIR

Custom directory path for browser cache & persistent session cookies.

~/.teams_puppeteer_profile

PUPPETEER_EXECUTABLE_PATH

Explicit path to your Chrome or Microsoft Edge executable.

Auto-detected

DEVTOOLS_PORT

Connect to an already running Chrome instance with remote debugging.

Auto-detected / 9222


πŸ§‘β€πŸ’» Manual Installation (For Developers / Contributors)

If you are developing or modifying the server locally:

git clone https://github.com/tinobruno/teams-puppeteer-mcp.git
cd teams-puppeteer-mcp
npm install
node index.js

πŸ”’ Privacy & Security

  • Local Storage Only: Your credentials, cookies, and chat contents remain strictly on your local machine inside .teams_puppeteer_profile/.

  • Zero Cloud Proxies: No data is ever routed through external third-party servers. All automation occurs directly between your local machine and Microsoft Teams endpoints.


πŸ“„ License

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

Available Tools

5 tools
get_last_messageA

PRIMARY TOOL to read the single latest message from a specific person, group, or channel in Teams. Supports partial names (e.g. 'Alice Smith', 'Bob', 'Project Alpha'). Automatically matches the chat and returns only the author, timestamp, and text. NEVER call list_teams_chats first.

Inputs: chat_name (required).

get_last_messagesA

Reads the last N messages from a specific Teams chat. Use this ONLY when the user asks for multiple recent messages or recent conversation history. NEVER call list_teams_chats first.

Inputs: chat_name (required), count.

get_last_unread_messageA

Reads unread messages. If 'chat_name' is provided, returns the latest unread message in that specific chat. If 'chat_name' is omitted, scans all Teams chats and returns a compact list of all unread messages with their senders and text in one single call. NEVER call list_teams_chats first.

Inputs: chat_name.

list_teams_chatsA

Lists chat names and activity timestamps from the Teams sidebar. Use ONLY when the user explicitly asks to list, see, or browse their conversations.

Inputs: limit.

send_teams_messageA

Sends a text message to a specified Microsoft Teams chat or group.

Inputs: message (required), chat_name (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 5 tools

    Disambiguation4/5

    The read tools overlap somewhatβ€”get_last_message, get_last_unread_message, and get_last_messages all retrieve recent messagesβ€”but their purposes are differentiated by unread status, scope, and message count. The descriptions are explicit about when to use each, so agent misselection is unlikely but still possible.

    Naming Consistency4/5

    Tool names mostly follow a clear verb_noun pattern: get_last_*, send_teams_message, list_teams_chats. The get_last_message and get_last_messages singular/plural distinction is a minor inconsistency, but the overall pattern is readable and predictable.

    Tool Count5/5

    With only five tools, the set is tightly scoped for Teams messaging operations. Each tool serves a distinct core needβ€”read latest, read unread, read history, send, listβ€”without unnecessary bloat.

    Completeness4/5

    The set covers the primary Teams workflows: reading recent messages, checking unread activity, sending messages, and listing conversations. Minor gaps exist such as marking messages as read or searching historical messages, but agents can accomplish most common tasks without dead ends.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to read and act on Microsoft Teams data through Microsoft Graph, covering team and channel operations, 1:1 and group chat messaging with rich formatting, message editing, deletion and search, file and image upload or download, and user directory lookups. Supports OAuth device-code authentication with token caching plus a read-only mode for safer, permission-limited access.
      12 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to interact with Microsoft Teams and Microsoft Graph, covering chats and channel messaging, message search, user and team member lookups, and file upload or attachment downloads. Supports OAuth device-code authentication, rich Markdown formatting, and LLM-friendly conversion of Teams HTML into Markdown.
      12 npm
      MIT