teams-mcp-server/README.md

Microsoft Teams MCP server with direct messaging support

# 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](https://portal.azure.com)
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

```bash
npm install -g teams-mcp-server
```

### From source

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

```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
MCP_SERVER_PORT=3000
DEBUG=true  # Optional: Enable debug logging
```

## Usage

### Running the Server

```bash
npm start
```

For development with auto-reload:
```bash
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\": \"user@example.com\"}]"
```

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

```
teams_create_chat --chatType "group" --topic "Project Discussion" --members "[{\"email\": \"user1@example.com\"}, {\"email\": \"user2@example.com\"}]"
```

#### 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):

```json
{
  "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:

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

```bash
# 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](https://github.com/mgklabs/teams-mcp-server/issues).