Teams Puppeteer MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Teams Puppeteer MCP Server what are my unread messages?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Teams Puppeteer MCP Server
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
npxwith 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.
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.jsonmacOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonLinux:
~/.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:
When your AI assistant invokes a Teams tool, a browser window will launch and navigate to Microsoft Teams (
https://teams.cloud.microsoft).Log in with your corporate SSO, password, and complete your Multi-Factor Authentication (MFA/2FA) prompt.
Once you reach the Teams chat interface, your session is automatically saved to your local profile directory (
~/.teams_puppeteer_profileon macOS/Linux, or%USERPROFILE%\\.teams_puppeteer_profileon Windows).Subsequent calls will automatically connect to your authenticated session.
π οΈ Available MCP Tools
Tool Name | Description | Parameters |
| Primary tool to read the single latest message from a contact, group, or channel. Matches partial names automatically. |
|
| Scans for unread messages. If |
|
| Retrieves the last N messages from a specific conversation. |
|
| Lists sidebar conversation names, unread flags, and latest activity timestamps. |
|
| Types and dispatches a message into Teams using native keyboard input into CKEditor 5. |
|
βοΈ 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 |
| Set to |
|
| Custom directory path for browser cache & persistent session cookies. |
|
| Explicit path to your Chrome or Microsoft Edge executable. | Auto-detected |
| Connect to an already running Chrome instance with remote debugging. | Auto-detected / |
π§βπ» 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 toolsget_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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
Undetectable cloud browser sessions for AI agents and scrapers. Navigate, extract, click, captcha.
Unofficial Browserless MCP β wraps the Browserless headless-Chromium REST API (browserless.io)
Cloud browser, web extraction, screenshots, and remote CDP tools for AI agents.
Browser automation MCP for whole web tasks in a cloud browser: saved logins, bot checks, replays.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables interaction with Microsoft Teams chats and channels using official Microsoft Graph API or Power Automate for enterprise environments with restricted permissions.91MIT
- AlicenseNot gradedqualityBmaintenanceEnables LLM agents to read from and write to Microsoft Teams via a real browser-based bridge, with support for multi-tenant profiles, chat listing, message reading and searching, team/channel listing, and sending messages.MIT
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT