msteams-mcp-server/README.md

Microsoft Teams MCP Server - Complete Teams integration for Claude Desktop and MCP clients with secure OAuth2 authentication and comprehensive team management

# 🚀 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**.

[![NPM Package](https://img.shields.io/badge/npm-msteams--mcp--server-blue)](https://www.npmjs.com/package/msteams-mcp-server)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-green)](https://nodejs.org/)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

## ✨ 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)
```bash
# 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
```bash
# 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):**
```json
{
  "mcpServers": {
    "teams": {
      "command": "npx",
      "args": ["msteams-mcp-server"]
    }
  }
}
```

**For Global Installation:**
```json
{
  "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 john@company.com as owner"
"Add sarah@company.com 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)

<details>
<summary>📋 Authentication Examples</summary>

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

// Check current status
{
  "tool": "teams_authenticate",
  "arguments": {
    "action": "status"
  }
}
```
</details>

<details>
<summary>💬 New Messaging Features</summary>

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

<details>
<summary>📁 File Management Examples</summary>

```javascript
// 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"
  }
}
```
</details>

<details>
<summary>👥 Group Chat Management</summary>

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

<details>
<summary>📅 Meeting Management</summary>

```javascript
// 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": ["alice@company.com", "bob@company.com"],
    "isRecordingEnabled": true
  }
}

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

<details>
<summary>🟢 Presence Management</summary>

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

## 🔧 Advanced Configuration

### Environment Variables (Custom Azure Apps)

For enterprise scenarios with custom Azure applications:

```bash
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

<details>
<summary>🏢 Enterprise Setup (Optional)</summary>

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

## 🔍 Troubleshooting

### Quick Diagnostics

```bash
# 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

<details>
<summary>🔐 Authentication Issues</summary>

**Problem**: Authentication fails or expires
```bash
# 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
</details>

<details>
<summary>🛠️ Server Issues</summary>

**Problem**: NPX command not found
```bash
# 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)
</details>

<details>
<summary>📊 Performance Issues</summary>

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

### Debug Mode

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

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

### Configuration Files Location

```bash
# 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

```bash
# 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](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- Uses [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/) for Teams integration
- Authentication powered by [MSAL Node](https://github.com/AzureAD/microsoft-authentication-library-for-js)
- Inspired by the Claude Desktop and SIYA Desktop communities

---

## 🚀 Get Started Now

```bash
# 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](#-troubleshooting) or [open an issue](https://github.com/your-org/msteams-mcp-server/issues).