Teams MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with Microsoft Teams through the Microsoft Graph API. Send messages, create chats, and manage conversations programmatically.

Features

• Send Messages: Send text and HTML messages to Teams chats
• Create Chats: Create one-on-one or group chats
• List Chats: Retrieve and filter user's chat list
• Read Messages: Get chat history and messages
• Secure Authentication: OAuth2 flow with PKCE and secure token storage
• Rate Limiting: Automatic handling of Microsoft Graph API limits

Prerequisites

• Node.js 18+
• Microsoft Teams account
• Azure app registration with appropriate permissions

Azure App Setup

1. Go to Azure Portal
2. Navigate to "Azure Active Directory" > "App registrations"
3. Click "New registration"
4. Configure your app:
   • Name: Teams MCP Server
   • Supported account types: "Accounts in this organizational directory only"
   • Redirect URI: http://localhost:3000/auth/callback (Web platform)
5. After creation, note the:
   • Application (client) ID
   • Directory (tenant) ID
6. Navigate to "API permissions" and add:
   • Microsoft Graph > Delegated permissions:
     • Chat.ReadWrite
     • ChatMessage.Send
     • User.Read
     • offline_access (for refresh tokens)
7. Grant admin consent for the permissions

Installation

Via npm

npm install -g teams-mcp-server

From source

git clone https://github.com/mgklabs/teams-mcp-server.git
cd teams-mcp-server
npm install
npm run build

Configuration

Create a .env file in your project directory:

AZURE_CLIENT_ID=your-app-client-id
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_SECRET=your-client-secret  # Optional: For confidential client flow
AZURE_REDIRECT_URI=http://localhost:3000/auth/callback
MCP_SERVER_PORT=3000
DEBUG=true  # Optional: Enable debug logging

Usage

Running the Server

npm start

For development with auto-reload:

npm run dev

Available MCP Tools

Once configured, the MCP server provides these tools:

Authentication

teams_auth_status

Check authentication status and initiate login if needed. This will open your browser for Microsoft authentication on first use.

List Chats

teams_list_chats

List all your Teams chats. Supports OData filtering:

teams_list_chats --filter "chatType eq 'oneOnOne'"

Create Chat

teams_create_chat --chatType "oneOnOne" --members "[{\"email\": \"[email protected]\"}]"

Create a new chat. For group chats, include a topic:

teams_create_chat --chatType "group" --topic "Project Discussion" --members "[{\"email\": \"[email protected]\"}, {\"email\": \"[email protected]\"}]"

Send Message

teams_send_message --chatId "chat-id" --content "Hello from MCP!"

Send HTML formatted messages:

teams_send_message --chatId "chat-id" --content "<b>Important:</b> Meeting at 3pm" --contentType "html"

Get Messages

teams_get_messages --chatId "chat-id" --limit 20

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "teams": {
      "command": "npx",
      "args": ["teams-mcp-server"],
      "env": {
        "AZURE_CLIENT_ID": "your-app-client-id",
        "AZURE_TENANT_ID": "your-tenant-id",
        "AZURE_CLIENT_SECRET": "your-client-secret",  // Optional: For confidential client flow
        "AZURE_REDIRECT_URI": "http://localhost:3000/auth/callback",  // Optional: Custom redirect URI
        "MCP_SERVER_PORT": "3000",  // Optional: Custom port
        "DEBUG": "true"  // Optional: Enable debug logging
      }
    }
  }
}

Other MCP Clients

For development or other MCP clients:

# With environment variables
AZURE_CLIENT_ID=your-client-id AZURE_TENANT_ID=your-tenant-id node dist/index.js

# Or with .env file
node dist/index.js

Authentication Flow

1. First tool usage triggers authentication check
2. If not authenticated, opens browser for Microsoft login
3. User grants permissions to the app
4. Tokens are securely stored for future use
5. Automatic token refresh before expiration

Security

• Uses OAuth2 public client flow (no client secret required)
• Tokens stored securely in system keychain (via keytar) with encrypted file fallback
• Automatic token refresh
• PKCE protection for authorization flow
• No credentials are logged or exposed

Troubleshooting

Debug Mode

Enable debug logging to troubleshoot issues:

DEBUG=true npm start

Debug logs are written to:

• Console output (stderr)
• File: .teams-mcp/debug.log

Authentication Issues

• Ensure redirect URI matches exactly in Azure and .env
• Check that all required permissions are granted
• Try clearing tokens: delete .teams-mcp/auth-cache
• Enable "Allow public client flows" in Azure app settings

Rate Limiting

• The server automatically handles rate limits
• Current usage is shown in teams_auth_status response
• Implements exponential backoff for retries

Common Errors

"Missing required environment variables" Ensure AZURE_CLIENT_ID and AZURE_TENANT_ID are set in your environment or .env file.

"Need admin approval" Your organization requires admin consent for the app permissions. Contact your IT administrator.

Port 3000 already in use Change the port by setting MCP_SERVER_PORT in your .env file.

Authentication errors

1. Clear stored tokens: The server stores tokens securely. If you have issues, try re-authenticating.
2. Verify redirect URI matches exactly: http://localhost:3000/auth/callback
3. Check app permissions in Azure Portal

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

# Type check
npm run typecheck

Architecture

• MCP Server: Implements Model Context Protocol for AI assistant integration
• Auth Manager: Handles OAuth2 flow with PKCE and secure token storage
• Teams Client: Wraps Microsoft Graph API calls with rate limiting
• Rate Limiter: Enforces Microsoft Graph API limits (10,000 requests/10 min)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and feature requests, please use the GitHub issues page.