msteams-mcp-server

🚀 Microsoft Teams MCP Server

A comprehensive Model Context Protocol (MCP) server that enables complete Microsoft Teams integration through natural language interactions. Built for Claude Desktop, SIYA Desktop, and any MCP-compatible application with production-ready security.

✨ Key Features

• 🎯 Complete Teams Management - Full control over teams, channels, members, and messages
• 💬 Advanced Messaging - Send messages, replies, reactions with rich formatting and mentions
• 📁 File Management - Upload, download, and manage files in teams and channels
• 👥 Group Chat Management - Create and manage group chats with multiple participants
• 📅 Meeting Management - Create online meetings and manage calendar events
• 🟢 Presence Management - Get and set user status and availability
• 🔐 Enterprise Security - OAuth2 redirect flow with secure token storage
• 🤖 AI-First Design - Intuitive tools perfect for natural language interactions
• 🌐 Cross-Platform - Works on macOS, Linux, and Windows
• ⚡ NPX Ready - Zero installation required, works out of the box

🛠️ Available Tools (12 Total)

🔐 Authentication

• authenticate - Complete authentication management (login, logout, status)

👥 Teams & Channel Management

• manage_teams - UNIFIED: List, search, create teams, and manage team members
• manage_channels - UNIFIED: List, search, and create channels within teams
• manage_members - UNIFIED: Add and remove team members with roles

💬 Messaging & Communication

• send_message - Send messages to team channels with rich formatting and mentions
• manage_messages - UNIFIED: Get and search messages in channels
• send_direct_message - Send direct/private messages to users
• get_direct_messages - Retrieve direct message conversations
• manage_reactions - NEW: Add/remove emoji reactions to messages (👍❤️😂😮😢😠)
• manage_replies - NEW: Reply to messages and get threaded conversations

📁 File Management

• manage_files - NEW: Upload, download, and list files in teams and channels

👥 Group Chat Management

• manage_group_chats - NEW: Create group chats, manage members, and chat settings

📅 Meeting & Calendar

• manage_meetings - NEW: Create online meetings, manage calendar events

🟢 Presence & Status

• manage_presence - NEW: Get and set user presence/status information

🔍 Search & Discovery

• search_users - Find users in your organization

🚀 Quick Start (2 Minutes)

Option A: NPX (Recommended - Zero Installation)

# 1. Authenticate with Microsoft Teams (one-time setup)
npx msteams-mcp-server --login

# 2. Verify authentication
npx msteams-mcp-server --verify-login

# 3. Add to Claude Desktop (see configuration below)
# 4. Start chatting with Claude about your Teams!

Option B: Global Installation

# Install globally
npm install -g msteams-mcp-server

# Authenticate
msteams-mcp-server --login

# Verify setup
msteams-mcp-server --verify-login

🔧 Claude Desktop Setup

1. Configuration File Location

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

2. Add MCP Server Configuration

For NPX (Recommended):

{
  "mcpServers": {
    "teams": {
      "command": "npx",
      "args": ["msteams-mcp-server"]
    }
  }
}

For Global Installation:

{
  "mcpServers": {
    "teams": {
      "command": "msteams-mcp-server"
    }
  }
}

3. Restart Claude Desktop

After adding the configuration, restart Claude Desktop to load the MCP server.

🔐 Authentication Flow

Step 1: Initial Authentication

When you first use the authenticate tool or any Teams command:

• Call authenticate tool:

  Use the authenticate tool with action "login"
  

• Get OAuth redirect URL: Claude will show you:

  🔐 Microsoft Teams Authentication Required
  
  🌐 Please complete authentication:
  1. Visit: [OAuth Authentication URL]
  2. Sign in with your Microsoft account
  3. Complete the authorization process
  
  💡 Direct link: [Click here to authenticate]
  

• Complete in browser: Follow the link and sign in with your Microsoft account

• Automatic completion: The system automatically detects when authentication is complete

Step 2: Using Teams Commands

Once authenticated, you can:

• "Show me my teams and their recent activity"
• "Create a new team called 'Project Alpha' with Alice and Bob"
• "Send a message to the general channel with a thumbs up reaction"
• "Upload this document to the project team's files"
• "Schedule a meeting for tomorrow at 2 PM with the development team"
• "Set my status to 'In a meeting' for the next 2 hours"

Authentication Actions

Action	Purpose	When to Use
login	Start OAuth redirect flow	First time or when tokens expire
status	Check current auth state	Verify you're logged in
logout	Clear all stored tokens	When switching accounts

💡 Usage Examples

Natural Language Commands (Talk to Claude)

🔵 Team Management:
"What teams am I a member of?"
"Create a new private team called 'Secret Project' with [e-mail] as owner"
"Add [e-mail] to the marketing team as an owner"
"List all channels in the development team"

🔵 Messaging & Communication:
"Send a message to the general channel saying 'Hello team! 👋'"
"Reply to the latest message in the project channel with 'Great work!'"
"Add a heart reaction to the latest message in the team chat"
"Send a direct message to Alice saying 'Can we schedule a call?'"

🔵 File Management:
"Upload the project plan document to the team files"
"List all files in the marketing channel"
"Download the latest budget spreadsheet from the finance team"

🔵 Group Chats:
"Create a group chat with Bob, Carol, and Dave for project discussion"
"List all my group chats"
"Add Emma to the project planning group chat"

🔵 Meeting Management:
"Create a meeting tomorrow at 2 PM for project review with the team"
"Show me my calendar events for this week"
"List all my online meetings"

🔵 Presence & Status:
"Set my status to 'Do Not Disturb' for the next hour"
"Check Alice's availability status"
"Show me the status of all development team members"

🔵 Advanced Operations:
"Search for messages containing 'project update' in the last 7 days"
"Find all files shared in the marketing channel this month"
"Get all replies to the latest announcement in the general channel"

Direct Tool Usage (Advanced)

📋 Authentication Examples

// Start authentication
{
  "tool": "teams_authenticate",
  "arguments": {
    "action": "login"
  }
}

// Check current status
{
  "tool": "teams_authenticate",
  "arguments": {
    "action": "status"
  }
}

💬 New Messaging Features

// Add reaction to message
{
  "tool": "manage_reactions",
  "arguments": {
    "action": "add",
    "messageType": "channel",
    "teamId": "team-id",
    "channelId": "channel-id", 
    "messageId": "message-id",
    "reactionType": "heart"
  }
}

// Reply to message
{
  "tool": "manage_replies",
  "arguments": {
    "action": "reply",
    "messageType": "channel",
    "teamId": "team-id",
    "channelId": "channel-id",
    "messageId": "message-id",
    "content": "Thanks for the update!"
  }
}

// Send direct message
{
  "tool": "send_direct_message",
  "arguments": {
    "displayName": "Alice Johnson",
    "content": "Can we schedule a quick call?"
  }
}

📁 File Management Examples

// Upload file to team
{
  "tool": "manage_files",
  "arguments": {
    "action": "upload",
    "location": "team",
    "teamId": "team-id",
    "fileName": "project-plan.pdf",
    "fileContent": "base64-encoded-content",
    "mimeType": "application/pdf"
  }
}

// List files in channel
{
  "tool": "manage_files", 
  "arguments": {
    "action": "list",
    "location": "channel",
    "teamId": "team-id",
    "channelId": "channel-id"
  }
}

// Download file
{
  "tool": "manage_files",
  "arguments": {
    "action": "download",
    "driveId": "drive-id",
    "itemId": "file-id"
  }
}

👥 Group Chat Management

// Create group chat
{
  "tool": "manage_group_chats",
  "arguments": {
    "action": "create",
    "topic": "Project Planning",
    "members": ["user1-id", "user2-id", "user3-id"]
  }
}

// List group chats
{
  "tool": "manage_group_chats",
  "arguments": {
    "action": "list"
  }
}

// Add members to group chat
{
  "tool": "manage_group_chats",
  "arguments": {
    "action": "add_members",
    "chatId": "chat-id",
    "members": ["new-user-id"]
  }
}

📅 Meeting Management

// Create online meeting
{
  "tool": "manage_meetings",
  "arguments": {
    "action": "create_meeting",
    "subject": "Project Review",
    "startDateTime": "2024-01-15T14:00:00Z",
    "endDateTime": "2024-01-15T15:00:00Z",
    "attendees": ["[e-mail]", "[e-mail]"],
    "isRecordingEnabled": true
  }
}

// Get calendar events
{
  "tool": "manage_meetings",
  "arguments": {
    "action": "get_calendar",
    "startTime": "2024-01-15T00:00:00Z",
    "endTime": "2024-01-22T23:59:59Z"
  }
}

🟢 Presence Management

// Set user presence
{
  "tool": "manage_presence",
  "arguments": {
    "action": "set_presence",
    "availability": "DoNotDisturb", 
    "activity": "InAMeeting",
    "expirationDuration": "PT2H"
  }
}

// Get user presence
{
  "tool": "manage_presence",
  "arguments": {
    "action": "get_presence",
    "userId": "user-id"
  }
}

// Get bulk presence
{
  "tool": "manage_presence",
  "arguments": {
    "action": "get_bulk_presence",
    "userIds": ["user1-id", "user2-id", "user3-id"]
  }
}

🔧 Advanced Configuration

Environment Variables (Custom Azure Apps)

For enterprise scenarios with custom Azure applications:

export TEAMS_CLIENT_ID="your-azure-app-client-id"
export TEAMS_TENANT_ID="your-tenant-id-or-common"
export TEAMS_CLIENT_SECRET="your-client-secret"
export TEAMS_REDIRECT_URI="http://localhost:44005/oauth2callback"
export TEAMS_AUTH_TYPE="redirect"  # OAuth redirect flow
export USER_ID="your-user-identifier"  # Used for OAuth state parameter

Azure App Registration Guide

🏢 Enterprise Setup (Optional)

For advanced scenarios or enterprise requirements:

• Go to Azure Portal: https://portal.azure.com

• Navigate to: Azure Active Directory > App registrations

• Create new registration:

  • Name: "Teams MCP Server"
  • Supported account types: Choose based on your needs
  • Redirect URI: http://localhost:44005/oauth2callback

• Configure API Permissions:

  Microsoft Graph > Delegated permissions:
  ✅ Team.ReadBasic.All           - List teams
  ✅ Team.Create                  - Create teams
  ✅ TeamMember.ReadWrite.All     - Manage members
  ✅ Channel.ReadBasic.All        - List channels
  ✅ ChannelMessage.Send          - Send messages
  ✅ ChannelMessage.ReadWrite     - Read/reply to messages
  ✅ Chat.ReadWrite               - Access chats and group chats
  ✅ ChatMessage.Send             - Send chat messages
  ✅ ChatMessage.Read             - Read chat messages
  ✅ OnlineMeetings.ReadWrite     - Manage meetings
  ✅ Calendars.ReadWrite          - Calendar access
  ✅ Presence.ReadWrite           - Read/write presence
  ✅ Files.ReadWrite.All          - File management
  ✅ User.Read                    - User profile
  ✅ Directory.Read.All           - Search users
  

• Grant admin consent for the permissions

• Get credentials and set environment variables

🔍 Troubleshooting

Quick Diagnostics

# Check if server is working
npx msteams-mcp-server --help

# Verify authentication
npx msteams-mcp-server --verify-login

# Test with MCP Inspector
npx @modelcontextprotocol/inspector npx msteams-mcp-server

# Check configuration directory
ls -la ~/.msteams-mcp/

Common Issues & Solutions

🔐 Authentication Issues

Problem: Authentication fails or expires

# Solution: Reset and re-authenticate
npx msteams-mcp-server --reset-auth
npx msteams-mcp-server --login

Problem: "Invalid client" error

• Ensure you're using the OAuth redirect authentication flow
• Check if your Azure app is configured as confidential or public client
• Verify redirect URI matches exactly: http://localhost:44005/oauth2callback

Problem: "Insufficient privileges"

• Check that your Azure app has the required Microsoft Graph permissions
• Ensure admin consent has been granted for the permissions
• Verify your user account has appropriate Teams licenses

🛠️ Server Issues

Problem: NPX command not found

# Ensure Node.js >= 18 is installed
node --version
npm --version

# If not installed, get Node.js from: https://nodejs.org/

Problem: MCP server won't start in Claude

• Check Claude Desktop configuration syntax
• Restart Claude Desktop completely
• Check console logs in Claude Desktop
• Verify server works standalone: npx msteams-mcp-server --help

Problem: "Permission denied" errors for new features

• Verify your Azure app has the new permissions (OnlineMeetings, Presence, Files)
• Re-grant admin consent after adding new permissions
• Some features require specific Teams licenses (e.g., meeting recording)

📊 Performance Issues

Problem: Slow responses

• Microsoft Graph API has rate limits
• Large teams/channels take longer to process
• Consider using maxResults parameter to limit data

Problem: File upload/download timeouts

• Large files may timeout during upload/download
• Check network connectivity and bandwidth
• Consider chunked upload for files > 4MB

Problem: Bulk operations slow

• Presence lookups and bulk operations are rate-limited
• Use reasonable batch sizes (recommended: 20-50 users max)

✅ Fixed: Timeout issues with core operations (v1.0.25)

• manage_teams list operations now use optimized direct HTTP requests
• manage_channels list operations bypass Graph SDK hanging issues
• manage_messages get operations use direct HTTP for better reliability
• manage_meetings list operations handle unsupported query parameters correctly
• All timeout issues with MCP framework have been resolved

Debug Mode

# Enable detailed logging
npx msteams-mcp-server --debug

# Check log files
cat /tmp/msteams-mcp-server.log

Configuration Files Location

# Configuration directory
ls ~/.msteams-mcp/

# Files stored:
# - credentials.json (if using custom Azure app)
# - msal-cache.json (token cache)
# - token.json (authentication tokens)

🛡️ Security & Privacy

Authentication Security

• OAuth2 Redirect Flow: Secure authorization code flow with PKCE
• Token Storage: Secure storage in user directory with restricted permissions
• Automatic Refresh: Tokens refreshed automatically before expiration
• Scoped Permissions: Only requests necessary Teams permissions

Data Privacy

• No Data Storage: Server doesn't store your Teams data permanently
• Local Processing: All operations happen locally on your machine
• Audit Trail: Check ~/.msteams-mcp/ for stored credentials and tokens
• Easy Cleanup: --reset-auth removes all stored authentication data

Enterprise Considerations

• Works with Azure AD B2B/B2C
• Supports conditional access policies
• Compatible with MFA requirements
• Audit logs available in Azure AD
• Compliant with enterprise security policies

📚 API Reference

Complete Tool Overview

Tool	Actions	Description
authenticate	login, logout, status	Authentication management
manage_teams	list, search, create, get, get_members	Team operations
manage_channels	list, search, create	Channel operations
send_message	-	Send channel messages
manage_messages	get, search	Retrieve and search messages
send_direct_message	-	Send direct/private messages
get_direct_messages	-	Get direct message conversations
manage_reactions	add, remove	Add/remove emoji reactions
manage_replies	reply, get_replies	Reply to messages and get threads
manage_files	upload, download, list	File management
manage_group_chats	create, list, get_members, add_members, remove_member	Group chat management
manage_meetings	create_meeting, list_meetings, get_calendar	Meeting and calendar management
manage_presence	get_presence, set_presence, get_bulk_presence	User presence/status
manage_members	add, remove	Team member management
search_users	-	Find users in organization

Supported Reaction Types

• 👍 like - Thumbs up
• ❤️ heart - Heart/love
• 😂 laugh - Laughing
• 😮 surprised - Surprised
• 😢 sad - Sad
• 😠 angry - Angry

Supported Presence States

Availability: Available, Busy, DoNotDisturb, BeRightBack, Away Activity: Available, Busy, DoNotDisturb, BeRightBack, Away, InAMeeting, InACall

🔄 Development

Local Development Setup

# Clone repository
git clone https://github.com/your-org/msteams-mcp-server.git
cd msteams-mcp-server

# Install dependencies
npm install

# Build project
npm run build

# Test locally
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector ./dist/index.js

Project Structure

msteams-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server with 12 tools
│   └── utils/
│       ├── api.ts            # Logging utilities
│       ├── credential-store.ts # Secure credential storage
│       ├── teams-auth.ts     # OAuth2 authentication
│       └── teams-operations.ts # Complete Teams API integration
├── bin/
│   └── cli.js               # NPX entry point
├── dist/                    # Compiled JavaScript
└── package.json            # NPM configuration

📈 Feature Status

✅ Completed Features

• Core Teams Management - Teams, channels, members
• Advanced Messaging - Messages, reactions, replies, mentions
• File Management - Upload, download, list files
• Group Chat Management - Create, manage group chats
• Meeting Management - Online meetings, calendar integration
• Presence Management - User status and availability
• Secure Authentication - OAuth2 flows, token management
• Direct Messaging - Private user-to-user communication

🔄 Future Enhancements

• Real-time notifications via webhooks
• Advanced search with filters and sorting
• Bulk operations for large-scale management
• Meeting recording management
• Advanced file permissions and sharing
• Teams app installation and management
• Analytics and usage reporting

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Built with the Model Context Protocol SDK
• Uses Microsoft Graph API for Teams integration
• Authentication powered by MSAL Node
• Inspired by the Claude Desktop and SIYA Desktop communities

🚀 Get Started Now

# One command to get started:
npx msteams-mcp-server --login

# With custom user identifier for OAuth state:
npx msteams-mcp-server --login --user-id "user123"

# With custom redirect URI for OAuth:
npx msteams-mcp-server --login --redirect-uri "http://localhost:8080/callback"

# Then add to Claude Desktop and start chatting:
"Show me my Teams and create a group chat with my project team!"

Ready to supercharge your Teams workflow with AI? 🚀

Questions? Check the troubleshooting section or open an issue.