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 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: Puppeteer 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.

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

⚙️ 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"
      }
    }
  }
}

🧑‍💻 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.