Teams MCP Server

An MCP (Model Context Protocol) server that enables AI assistants to interact with Microsoft Teams. Search messages, send replies, manage favourites, and more.

Fork notice. This project began as a fork of m0nkmaster/msteams-mcp by Rob MacDonald (MIT), and is now maintained and released independently as @shayanline/msteams-mcp with a substantially expanded tool set (chat management, files, tasks, scheduling, pin/mute, and more). Sincere thanks to the original author for the foundation the project is built on.

How It Works

This server calls Microsoft's Teams APIs directly (Substrate, chatsvc, CSA) - the same APIs the Teams web app uses. No Azure AD app registration or admin consent required.

Authentication flow:

1. AI runs teams_login to open a browser for you to log in
2. OAuth tokens are extracted and cached
3. All operations use cached tokens directly (no browser needed)
4. Automatic token refresh (~1 hour)

Security: Uses the same authentication as the Teams web client - your access is limited to what your account can already do.

Installation

Prerequisites

• Node.js 18+
• A Microsoft account with Teams access
• Google Chrome, Microsoft Edge, or Chromium browser installed

Configure Your MCP Client

Add to your MCP client configuration (e.g., Claude Desktop, Windsurf, Cursor):

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

That's it. npx will automatically download and run the latest version.

From Source (alternative)

If you prefer to run from a local clone:

git clone https://github.com/shayanline/msteams-mcp.git
cd msteams-mcp
npm install && npm run build

Then configure your MCP client:

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

The server uses your system's Chrome (macOS/Linux) or Edge (Windows) for authentication.

Available Tools

Search & Discovery

| Tool | Description | |------|-------------| | teams_search | Search Teams messages with operators (from:, sent:, in:, hasattachment:, etc.) | | teams_search_email | Search emails in your mailbox (same auth as Teams — no extra login) | | teams_get_message | Get a single message by ID with full content (any age) | | teams_get_thread | Get messages from a conversation/thread | | teams_find_channel | Find channels by name (your teams + org-wide discovery) | | teams_get_activity | Get activity feed (mentions, reactions, replies, notifications) |

Messaging

| Tool | Description | |------|-------------| | teams_send_message | Send a message (default: self-chat/notes). Use replyToMessageId for thread replies, importance (high/urgent) for priority, subject for a channel post title | | teams_edit_message | Edit one of your own messages | | teams_delete_message | Delete one of your own messages (soft delete) | | teams_forward_message | Forward a message to another conversation. Preserves the quoted block (sender + content) and carries original file attachments as native chiclets with no re-upload. An optional comment is prepended above the quote |

People & Contacts

| Tool | Description | |------|-------------| | teams_get_me | Get current user profile (email, name, ID) | | teams_search_people | Search for people by name or email | | teams_get_frequent_contacts | Get frequently contacted people (useful for name resolution) | | teams_get_chat | Get conversation ID for 1:1 chat with a person | | teams_create_group_chat | Create a new group chat with multiple people (2+ others) | | teams_get_presence | Get real time presence (availability, activity, device, out of office) for one or more people |

Organisation

| Tool | Description | |------|-------------| | teams_get_favorites | Get pinned/favourite conversations | | teams_add_favorite | Pin a conversation | | teams_remove_favorite | Unpin a conversation | | teams_save_message | Bookmark a message | | teams_unsave_message | Remove bookmark from a message | | teams_get_saved_messages | Get list of saved/bookmarked messages with source references | | teams_get_followed_threads | Get list of followed threads with source references | | teams_get_unread | Get unread counts (aggregate or per-conversation) | | teams_mark_read | Mark a conversation as read up to a message | | teams_mark_unread | Mark a conversation unread from a chosen message onward | | teams_list_chats | Browse recent conversations (chats, group chats, channels, meetings) with topic, type, favourite, unread, last message | | teams_list_teams | List all teams you belong to, each with its channels |

Chat management

| Tool | Description | |------|-------------| | teams_get_chat_members | List the members of a group chat or channel (MRI and role) | | teams_rename_chat | Rename a group chat (set its topic) | | teams_add_member | Add a person to a group chat | | teams_remove_member | Remove a person from a group chat | | teams_leave_chat | Leave a group chat | | teams_create_channel | Create a new channel in a team (standard or private) | | teams_delete_channel | Delete a channel from a team (permanent; General cannot be deleted) | | teams_pin_message | Pin a message in a conversation | | teams_unpin_message | Clear pinned messages in a conversation | | teams_mute_chat | Mute a conversation (notifications off) | | teams_unmute_chat | Unmute a conversation |

Reactions

| Tool | Description | |------|-------------| | teams_search_emoji | Search for emojis by name (standard + custom org emojis) | | teams_add_reaction | Add an emoji reaction to a message | | teams_remove_reaction | Remove an emoji reaction from a message |

Quick reactions: like, heart, laugh, surprised, sad, angry can be used directly without searching.

Calendar & Meetings

| Tool | Description | |------|-------------| | teams_get_meetings | Get meetings from calendar (defaults to next 7 days) | | teams_get_meeting | Get full details of a single event by ID (attendees, body, location, join URL) | | teams_create_meeting | Create a calendar meeting and send invites (Teams join link by default) | | teams_update_meeting | Update or reschedule an existing event (only provided fields change) | | teams_cancel_meeting | Cancel an event (organiser notifies attendees; attendee removes from own calendar) | | teams_respond_to_meeting | Accept, tentatively accept, or decline a meeting invite | | teams_get_schedule | Check free/busy availability for one or more people over a time window | | teams_find_meeting_times | Suggest meeting slots that work across attendees (ranked by confidence) | | teams_get_transcript | Get meeting transcript (requires threadId from teams_get_meetings) | | teams_get_recording | Get meeting recording playback/download URLs + metadata (requires threadId from teams_get_meetings) |

teams_get_meetings returns: subject, times, organiser, join URL, threadId for meeting chat. Use threadId with teams_get_thread to read meeting chat, with teams_get_transcript to get the full transcript with speakers and timestamps, or with teams_get_recording to get the recording's playback and download URLs.

Files

| Tool | Description | |------|-------------| | teams_get_shared_files | Get files and links shared in a conversation (supports pagination) | | teams_list_files | Browse files and folders in your OneDrive | | teams_upload_file | Upload a local file to your OneDrive (up to 250 MB) | | teams_download_file | Download a OneDrive file by item id to a local path | | teams_download_shared_file | Download a file shared in a Teams conversation by its SharePoint/OneDrive URL (e.g. from teams_get_shared_files). Works for files from other users' drives that you have access to | | teams_send_file | Send a local file into a conversation as a native attachment (real file chiclet, also appears in the Files tab) | | teams_send_files | Send several local files into a conversation as native attachments on a single message (one message, multiple file chiclets) |

teams_get_shared_files returns both files (name, extension, URL, size) and links (URL, title), along with who shared each item. Works for channels, group chats, 1:1 chats, and meeting chats.

teams_send_file posts a native file attachment (a real file chiclet, not just a link), and uploads the file to the right place for the conversation type, matching the Teams client: for a channel it goes into the channel's own SharePoint files folder (so it shows in the channel Files tab); for chats (1:1, group, meeting, self) it goes into your OneDrive "Microsoft Teams Chat Files" and is shared with the conversation via an organisation link.

teams_send_files does the same but attaches multiple files to one message, so you get a single post carrying several file chiclets rather than one message per file. Pass localPaths (an array) and an optional caption.

Tasks (Microsoft To Do)

| Tool | Description | |------|-------------| | teams_list_task_lists | List your To Do task lists | | teams_list_tasks | List tasks in a list (defaults to the default list, open tasks only) | | teams_create_task | Create a task (title, optional due date, note, importance) | | teams_complete_task | Mark a task complete or reopen it |

Session

| Tool | Description | |------|-------------| | teams_login | Trigger manual login (opens browser) | | teams_status | Check authentication and session state |

Search Operators

Both teams_search (Teams messages) and teams_search_email (emails) support native operators:

from:[email protected]     # Messages/emails from person
sent:2026-01-20            # From specific date
sent:>=2026-01-15          # Since date
in:project-alpha           # Messages in channel (Teams only)
subject:"budget"           # By subject (email)
"Rob Smith"                # Find @mentions (name in quotes)
hasattachment:true         # With files
is:unread                  # Unread emails (email only)
NOT from:[email protected]      # Exclude results

Combine operators: from:[email protected] sent:>=2026-01-18 hasattachment:true

Note: @me, from:me, to:me do NOT work. Use teams_get_me first to get your email/displayName. sent:today works, but sent:lastweek and sent:thisweek do NOT - use explicit dates or omit (results are sorted by recency).

MCP Resources

The server also exposes passive resources for context discovery:

| Resource URI | Description | |--------------|-------------| | teams://me/profile | Current user's profile | | teams://me/favorites | Pinned conversations | | teams://status | Authentication status |

CLI Tools (Development)

For local development, CLI tools are available for testing and debugging:

# Check authentication status
npm run cli -- status

# Search messages
npm run cli -- search "meeting notes"
npm run cli -- search "project" --from 0 --size 50

# Search emails
npm run cli -- teams_search_email --query "from:[email protected]"

# Send messages (default: your own notes/self-chat)
npm run cli -- send "Hello from Teams MCP!"
npm run cli -- send "Message" --to "conversation-id"

# Force login
npm run cli -- login --force

# Output as JSON
npm run cli -- search "query" --json

MCP Test Harness

Test the server through the actual MCP protocol:

# List available tools
npm run cli

# Call any tool
npm run cli -- search "your query"
npm run cli -- status
npm run cli -- people "john smith"
npm run cli -- favorites
npm run cli -- activity              # Get activity feed
npm run cli -- unread                # Check unread counts
npm run cli -- teams_search_emoji --query "heart"  # Search emojis

Limitations

• Login required - Run teams_login to authenticate (opens browser)
• Token expiry - Tokens expire after ~1 hour; headless refresh is attempted or run teams_login again when needed
• Undocumented APIs - Uses Microsoft's internal APIs which may change without notice
• Search limitations - Full-text search only; thread replies not matching search terms won't appear (use teams_get_thread for full context)
• Own messages only - Edit/delete only works on your own messages

Session Files

Session files are stored in a user config directory (encrypted):

• macOS/Linux: ~/.teams-mcp-server/
• Windows: %APPDATA%\teams-mcp-server\

Contents: session-state.json, token-cache.json, browser-profile/

If your session expires, call teams_login or delete the config directory.

Development

For local development:

git clone https://github.com/shayanline/msteams-mcp.git
cd msteams-mcp
npm install
npm run build

Development commands:

npm run dev          # Run MCP server in dev mode
npm run build        # Compile TypeScript
npm run lint         # Run ESLint
npm run research     # Explore Teams APIs (logs network calls)
npm test             # Run unit tests
npm run typecheck    # TypeScript type checking

For development with hot reload, configure your MCP client:

{
  "mcpServers": {
    "teams": {
      "command": "npx",
      "args": ["tsx", "/path/to/msteams-mcp/src/index.ts"]
    }
  }
}

See AGENTS.md for detailed architecture and contribution guidelines.

Teams Chat Export Bookmarklet

This repo also includes a standalone bookmarklet for exporting Teams chat messages to Markdown. See teams-bookmarklet/README.md.