🚀 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:

1. Call authenticate tool:

   Use the authenticate tool with action "login"

2. 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]

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

4. 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 [email protected] as owner"
"Add [email protected] 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)

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

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

// 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?"
  }
}

// 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"
  }
}

// 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"]
  }
}

// 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": ["[email protected]", "[email protected]"],
    "isRecordingEnabled": true
  }
}

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

// 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

For advanced scenarios or enterprise requirements:

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

2. Navigate to: Azure Active Directory > App registrations

3. Create new registration:

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

4. 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

5. Grant admin consent for the permissions

6. 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

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

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

1. Check Claude Desktop configuration syntax
2. Restart Claude Desktop completely
3. Check console logs in Claude Desktop
4. 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)

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.