teams-mcp

Microsoft Teams MCP Server — control Teams through Claude using headless Playwright browser automation.

24 tools across messaging, channels, meetings, files, and presence — all accessible through Claude Code or any MCP-compatible client.

How It Works

Uses Playwright to automate the Teams web app (teams.microsoft.com). The browser launches on the first tool call and auto-closes after 5 minutes of inactivity.

Auth flow: On first use (or when the session expires), a visible browser opens for you to sign in with your Microsoft account (supports MFA). After sign-in, the session is saved and all subsequent operations run headless in the background.

Installation

npx @dev-hitesh-gupta/teams-mcp

Or install globally:

npm install -g @dev-hitesh-gupta/teams-mcp

Install Chromium browser

npx playwright install chromium

Authenticate

npx @dev-hitesh-gupta/teams-mcp auth
# or if installed globally:
teams-mcp auth

A browser window will open — sign in with your Microsoft account. Your session is saved to ~/.teams-mcp/ and reused on future calls.

Add to Claude Code

claude mcp add teams -- npx @dev-hitesh-gupta/teams-mcp

Or add manually to your Claude config (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "teams": {
      "command": "npx",
      "args": ["@dev-hitesh-gupta/teams-mcp"]
    }
  }
}

Tools

Messages (8)

| Tool | Description | |------|-------------| | teams_list_chats | List recent chats (1:1, group, meeting chats) | | teams_get_messages | Read messages from a chat or channel | | teams_send_message | Send a message to a chat or channel | | teams_reply_to_message | Reply in a message thread | | teams_react_to_message | Add emoji reaction (like/heart/laugh/surprised/sad/angry) | | teams_search_messages | Search across all chats and channels | | teams_get_mentions | Get @mention notifications from activity feed | | teams_delete_message | Delete a sent message |

Channels & Teams (6)

| Tool | Description | |------|-------------| | teams_list_teams | List all joined teams | | teams_list_channels | List channels in a team | | teams_create_channel | Create a new standard or private channel | | teams_get_channel_info | Get channel details and metadata | | teams_list_members | List team or channel members | | teams_pin_message | Pin or unpin a message in a channel |

Meetings (4)

| Tool | Description | |------|-------------| | teams_list_meetings | List upcoming calendar meetings | | teams_create_meeting | Schedule a new Teams meeting | | teams_get_meeting_info | Get meeting details and join link | | teams_join_meeting | Get the join URL for a meeting |

Files (3)

| Tool | Description | |------|-------------| | teams_list_files | List files in a channel's Files tab | | teams_upload_file | Upload a local file to a channel | | teams_download_file | Download a file from a channel to a local path |

Presence & Status (3)

| Tool | Description | |------|-------------| | teams_set_status | Set presence status (Available/Busy/DND/Away/Offline) | | teams_set_status_message | Set a custom status message | | teams_get_notifications | Get activity feed notifications |

Configuration

Optional environment variables:

| Variable | Default | Description | |----------|---------|-------------| | TEAMS_MCP_IDLE_TIMEOUT | 300000 (5 min) | Browser idle timeout in milliseconds | | TEAMS_MCP_TOOL_TIMEOUT | 30000 (30 sec) | Per-tool operation timeout in milliseconds |

Example with custom timeout:

{
  "mcpServers": {
    "teams": {
      "command": "npx",
      "args": ["@dev-hitesh-gupta/teams-mcp"],
      "env": {
        "TEAMS_MCP_IDLE_TIMEOUT": "600000"
      }
    }
  }
}

Data & Auth Storage

All data is stored locally on your machine:

~/.teams-mcp/
├── auth-state.json     # Saved browser session (cookies, storage)
├── config.json         # Optional config overrides
└── debug/              # Error screenshots for debugging

Re-authentication

If your session expires, the server automatically opens a visible browser for re-auth. You can also manually trigger it:

npx @dev-hitesh-gupta/teams-mcp auth
# or reset completely:
rm ~/.teams-mcp/auth-state.json && npx @dev-hitesh-gupta/teams-mcp auth

Troubleshooting

Auth not working / stuck on login:

rm ~/.teams-mcp/auth-state.json
npx @dev-hitesh-gupta/teams-mcp auth

Tool failing silently: Check screenshots in ~/.teams-mcp/debug/ — errors are automatically captured.

Teams UI changed / selectors breaking: If a tool stops working after a Teams update, the DOM selectors may need updating. Open an issue on GitHub.

Rate limits or throttling: Increase TEAMS_MCP_TOOL_TIMEOUT and add pauses between tool calls.

Requirements

• Node.js 18+
• Chromium (installed via npx playwright install chromium)
• A Microsoft account (personal or work/school with Teams access)

License

MIT — Hitesh Gupta