Microsoft365-mcp-server

doto-psh/Microsoft365-mcp-server

3.2

If you are the rightful owner of Microsoft365-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Microsoft 365 MCP Server is a robust Model Context Protocol server designed for seamless integration with Microsoft 365, offering enterprise-grade security and OAuth 2.1 authentication.

Tools
5
Resources
0
Prompts
0

Microsoft 365 MCP Server

GitHub release Python FastMCP

A powerful Model Context Protocol (MCP) server for seamless Microsoft 365 integration with enterprise-grade security and OAuth 2.1 authentication.

Features • Quick Start • Documentation • Contributing

✨ Features

  • 🔐 Enterprise Security: OAuth 2.1 with PKCE support and automatic session management
  • 🏢 Multi-tenant Support: Secure user isolation and tenant-specific configurations
  • 🚀 High Performance: Built on FastMCP framework with streamable HTTP transport
  • 📊 Comprehensive API: Full Microsoft Graph API integration for Microsoft 365 operations
  • 🔄 Auto Token Management: Automatic token refresh and credential persistence
  • 🐳 Docker Ready: Production-ready containerization with health checks

Supported Operations

CategoryOperations
AuthenticationOAuth flow initiation, status checking, logout
Teams ManagementList teams, channels, team info, member management
SharePointSites, drives, document libraries, files
OneDriveSearch files, list folders, get download URL
OutlookSend, drafts, read, list messages
Chat OperationsDirect messaging, group chats, message history
Search & DiscoveryAdvanced search across teams, messages, and users
User ManagementProfile access, presence status, directory lookup

🚀 Quick Start

Prerequisites

  • Python 3.10 or higher
  • uv package manager
  • Microsoft Azure App Registration (Setup Guide)

Installation

Option 1: Docker (Recommended)
# Clone the repository
git clone https://github.com/doto-psh/ms365-mcp.git
cd ms365-mcp

# Configure environment variables
cp .env.oauth21 .env
# Edit .env with your Microsoft OAuth credentials

# Start with Docker Compose
docker compose up -d

# Verify installation
curl http://localhost:8003/health
Option 2: Local Development
# Clone and setup
git clone https://github.com/doto-psh/ms365-mcp.git
cd ms365-mcp

# Create virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e .

# Configure environment
cp .env.oauth21 .env
# Edit .env with your credentials

# Start the server
uv run main.py --transport streamable-http --port 8003

Azure Setup

  1. Register Application:

    • Go to Azure Portal → App Registrations
    • Create new registration with redirect URI: http://localhost:8003/callback

  2. Configure API Permissions:

    Microsoft Graph (Delegated):
├── User.Read
├── Team.ReadBasic.All
├── Channel.ReadBasic.All
├── ChannelMessage.Read.All
├── Chat.Read
└── TeamMember.Read.All

  3. Update Configuration:

    # .env file
MICROSOFT_OAUTH_CLIENT_ID="your-application-id"
MICROSOFT_OAUTH_CLIENT_SECRET="your-client-secret"
MICROSOFT_TENANT_ID="common"  # or specific tenant ID

📖 Usage

Authentication Flow

# 1. Start authentication
curl -X POST http://localhost:8003/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "start_microsoft_auth",
      "arguments": {"user_email": "user@example.com"}
    },
    "id": 1
  }'

# 2. Follow the OAuth URL from response
# 3. Use other tools after authentication

Available Tools

Authentication Tools
  • start_microsoft_auth(user_email) - Initiate OAuth flow
  • logout_microsoft_auth(user_email) - Clear user session
  • check_microsoft_auth_status(user_email) - Check authentication status
Teams Management
  • list_teams(user_email) - List user's Teams
  • list_channels(user_email, team_id) - List team channels
  • get_team_info(user_email, team_id) - Get team details
  • list_team_members(user_email, team_id) - List team members
Chat Operations
  • list_chats(user_email) - List user's chats
  • get_chat_messages(user_email, chat_id) - Get chat messages
  • send_message(user_email, chat_id, message) - Send message

🏗️ Architecture

Security Model

graph TB
    A[Client Request] --> B[MCP Session Middleware]
    B --> C[Auth Info Middleware]
    C --> D[Service Decorator]
    D --> E{Auth Validation}
    E -->|Valid| F[Microsoft Graph API]
    E -->|Invalid| G[Auth Required Response]
    F --> H[Response to Client]
    G --> H

Key Components

  • OAuth21SessionStore: Multi-user session management with immutable bindings
  • Service Decorators: Automatic authentication and authorization
  • Graph Service: Optimized Microsoft Graph API client
  • Transport Layer: Support for both HTTP and stdio protocols

🔧 Configuration

Environment Variables

# Required: Microsoft OAuth Configuration
MICROSOFT_OAUTH_CLIENT_ID="your-client-id"
MICROSOFT_OAUTH_CLIENT_SECRET="your-client-secret"
MICROSOFT_TENANT_ID="common"

# Server Configuration
TEAMS_MCP_BASE_URI="http://localhost"
TEAMS_MCP_PORT=8003
MICROSOFT_OAUTH_REDIRECT_URI="http://localhost:8003/callback"

# OAuth 2.1 Settings
MCP_ENABLE_OAUTH21=true
OAUTH2_ALLOW_INSECURE_TRANSPORT=false  # Set true for local dev

# Optional: Advanced Settings
LOG_LEVEL=INFO
MCP_SINGLE_USER_MODE=false

Docker Configuration

# docker-compose.yml
services:
  teams-mcp-server:
    build: .
    ports:
      - "8003:8003"
    environment:
      - MICROSOFT_OAUTH_CLIENT_ID=${MICROSOFT_OAUTH_CLIENT_ID}
      - MICROSOFT_OAUTH_CLIENT_SECRET=${MICROSOFT_OAUTH_CLIENT_SECRET}
      - MICROSOFT_TENANT_ID=${MICROSOFT_TENANT_ID:-common}
      - MCP_ENABLE_OAUTH21=true
    volumes:
      - teams_mcp_credentials:/app/.microsoft365_mcp/credentials
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8003/health"]
      interval: 30s
      timeout: 10s
      retries: 3

🔍 Troubleshooting

Common Issues

Authentication Failures

Problem: OAuth authentication fails

# Check configuration
curl http://localhost:8003/health

# Verify Azure app permissions
# Ensure redirect URI matches exactly
# Check tenant ID configuration

Solution:

  • Verify all environment variables are set correctly
  • Check Azure app registration permissions
  • Ensure redirect URI matches: http://localhost:8003/callback
Token Expiration

Problem: "Token expired" errors

# Check token status
curl -X POST http://localhost:8003/mcp \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"check_microsoft_auth_status","arguments":{"user_email":"user@example.com"}},"id":1}'

Solution: Tokens are automatically refreshed. If refresh fails, re-authenticate using start_microsoft_auth.

Permission Denied

Problem: "Access denied" when calling tools

Solution:

  • Verify Microsoft Graph API permissions in Azure
  • Check user has access to requested Teams/chats
  • Ensure proper admin consent for organization-wide permissions

Debug Mode

# Enable debug logging
LOG_LEVEL=DEBUG uv run main.py --transport streamable-http

# Check logs
tail -f teams_mcp_server_debug.log

🤝 Contributing

We welcome contributions! Please see our for details.

Development Setup

# Clone and setup development environment
git clone https://github.com/doto-psh/ms365-mcp.git
cd ms365-mcp

# Install with development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Code formatting
black .
isort .

# Type checking
mypy .

Project Structure

ms365-mcp/
├── auth/                   # Authentication & OAuth management
├── core/                   # Core MCP server components  
├── teams/                  # Teams-specific tools & operations
├── main.py                 # Server entry point
├── docker-compose.yaml     # Docker configuration
└── tests/                  # Test suite

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

📞 Support

⬆ Back to Top

Made with ❤️ by the Microsoft Teams MCP community