microsoft-mcp-server

Martian-Engineering/microsoft-mcp-server

3.2

If you are the rightful owner of microsoft-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 henry@mcphub.com.

An MCP server that integrates Microsoft Graph API with OAuth authentication, acting as a bridge between MCP hosts/clients and Microsoft APIs using a MITM OAuth pattern.

Tools
5
Resources
0
Prompts
0

Microsoft MCP Server

An MCP (Model Context Protocol) server that provides Microsoft Graph API integration with OAuth authentication. This server acts as a bridge between MCP hosts/clients and Microsoft APIs using a MITM (Man-in-the-Middle) OAuth pattern.

Features

  • Microsoft Calendar Integration: List calendars, view events, create/update/delete events with full Microsoft 365 calendar support
  • OAuth Authentication: Secure authentication flow bridging MCP hosts/clients with Azure AD OAuth
  • Dynamic Client Registration: Supports MCP OAuth client registration
  • MSAL Integration: Uses Microsoft Authentication Library for robust Azure AD authentication
  • Automatic Token Refresh: Maintains access using Microsoft refresh tokens
  • Comprehensive Error Handling: Maps Microsoft Graph errors to meaningful responses

Prerequisites

  • Python 3.11+
  • Azure AD account with app registration capabilities
  • ngrok account (free tier is sufficient)

Quick Start

Step 1: Azure AD App Setup

  1. Go to Azure Portal
  2. Navigate to Azure Active Directory ā†’ App registrations
  3. Click "New registration"
  4. Configure your app:
    • Name: MCP Microsoft Server (or your preference)
    • Supported account types: Choose based on your needs
    • Redirect URI: Will be configured after ngrok setup
  5. After creation, note down:
    • Application (client) ID
    • Directory (tenant) ID
  6. Create a client secret:
    • Go to Certificates & secrets
    • New client secret
    • Save the secret value immediately (shown only once)
  7. Grant API permissions:
    • Go to API permissions
    • Add permission ā†’ Microsoft Graph ā†’ Delegated permissions
    • Select: User.Read, Calendars.ReadWrite
    • Grant admin consent (if required)

Step 2: Start ngrok tunnel

Set up and start ngrok to expose your local server:

# Install ngrok if needed
# macOS: brew install ngrok
# Linux: See https://ngrok.com/download

# Configure ngrok (first time only)
ngrok config add-authtoken YOUR-AUTH-TOKEN

# Start tunnel
ngrok http 8000

Note the HTTPS URL (e.g., https://abc123.ngrok-free.app)

Step 3: Configure Azure AD Redirect URI

  1. Return to your Azure AD app registration
  2. Go to Authentication ā†’ Add a platform ā†’ Web
  3. Add redirect URI: https://YOUR-NGROK-URL.ngrok-free.app/microsoft/callback
  4. Save changes

Step 4: Launch the server

./launch-server.py

The script will:

  • Prompt for your Azure AD credentials if not configured
  • Set up Python virtual environment
  • Install dependencies
  • Start the MCP server

Claude Desktop Configuration

Add the server to Claude Desktop:

  1. Open Claude Desktop ā†’ Settings ā†’ Developer
  2. Add new MCP server with your ngrok URL:
    • For SSE transport: https://YOUR-NGROK-URL.ngrok-free.app/sse
    • For streamable-http: https://YOUR-NGROK-URL.ngrok-free.app
  3. Complete the OAuth flow when prompted
  4. Calendar tools will now be available!

Available Tools

Microsoft Calendar

  • list_calendars - List all accessible Microsoft 365 calendars
  • list_events - List events from a calendar with optional time range and filters
  • get_event - Get details of a specific event
  • create_event - Create a new calendar event with attendees, location, reminders
  • delete_event - Delete a calendar event

Coming Soon

  • Mail/Outlook: Send emails, manage inbox, folders
  • Teams: Send messages, manage teams and channels
  • OneDrive/SharePoint: File operations, document management

Environment Variables

Required:

  • MCP_MICROSOFT_CLIENT_ID - Azure AD application (client) ID
  • MCP_MICROSOFT_CLIENT_SECRET - Client secret value
  • MCP_MICROSOFT_TENANT_ID - Directory (tenant) ID (use "common" for multi-tenant)

Optional:

  • MCP_MICROSOFT_SERVER_URL_OVERRIDE - Override server URL (automatically set with ngrok)
  • MCP_SERVER_TRANSPORT - Transport type: sse or streamable-http (default)
  • MCP_SERVER_PORT - Server port (default: 8000)
  • MCP_SERVER_HOST - Server host (default: localhost)

How It Works

OAuth Flow (MITM Pattern)

This server implements a Man-in-the-Middle OAuth pattern to bridge MCP hosts/clients with Microsoft's OAuth:

MCP Host/Client ā†’ Our Server ā†’ Azure AD ā†’ User
  1. Discovery: MCP host discovers OAuth endpoints via /.well-known/oauth-authorization-server
  2. Registration: MCP host registers as a client via Dynamic Client Registration
  3. Authorization:
    • MCP host requests authorization
    • Our server redirects to Microsoft login with our app credentials
    • User authenticates with Microsoft
    • Azure AD redirects back to our server
    • Our server redirects to MCP host with an MCP authorization code
  4. Token Exchange: MCP host exchanges the code for MCP tokens
  5. API Calls: MCP tokens are internally mapped to Microsoft access tokens for Graph API access

Architecture

  • Authentication: MSAL (Microsoft Authentication Library) for Azure AD OAuth
  • API Client: msgraph-sdk for Microsoft Graph API calls
  • Framework: FastMCP with MCP 1.0+ protocol support
  • Transport: Streamable-HTTP (default) or SSE

Troubleshooting

Common Issues

  1. "Id is malformed" errors:

    • This can occur intermittently with get_event/delete_event
    • Usually related to session state or caching
    • Try creating a new event and immediately operating on it

  2. 403 Forbidden Errors:

    • Verify all required permissions are granted in Azure AD
    • Check that admin consent is granted if required
    • Ensure the user has access to the requested resources

  3. OAuth Redirect Mismatch:

    • Ensure the redirect URI in Azure AD matches exactly
    • Include /microsoft/callback at the end
    • Use HTTPS (via ngrok) not HTTP

  4. Connection Issues:

    • Verify ngrok is running and accessible
    • Check firewall/proxy settings
    • Ensure environment variables are set correctly

Logging

The server uses structured logging to stdout. To see detailed logs:

# Run with debug logging
MCP_LOG_LEVEL=DEBUG ./launch-server.py

Development

Project Structure

microsoft_mcp/
ā”œā”€ā”€ __init__.py
ā”œā”€ā”€ server.py          # FastMCP server setup and entry point
ā”œā”€ā”€ settings.py        # Configuration via environment variables
ā”œā”€ā”€ auth/
ā”‚   ā”œā”€ā”€ __init__.py
ā”‚   ā””ā”€ā”€ provider.py    # MITM OAuth provider implementation
ā”œā”€ā”€ tools/
ā”‚   ā””ā”€ā”€ calendar/      # Calendar tool implementations
ā”‚       ā”œā”€ā”€ create_event.py
ā”‚       ā”œā”€ā”€ delete_event.py
ā”‚       ā”œā”€ā”€ get_event.py
ā”‚       ā”œā”€ā”€ list_calendars.py
ā”‚       ā”œā”€ā”€ list_events.py
ā”‚       ā””ā”€ā”€ utils.py   # Graph API wrapper utilities
ā””ā”€ā”€ utils/
    ā”œā”€ā”€ errors.py      # Error definitions
    ā”œā”€ā”€ error_handlers.py
    ā””ā”€ā”€ rate_limiter.py

Adding New Tools

To add new Microsoft Graph services:

  1. Create a new directory under tools/ (e.g., mail/)
  2. Implement individual tool files with register_<tool_name>_tool() functions
  3. Import and register tools in server.py
  4. Add required Graph API permissions to the scope list in settings.py
  5. Update Azure AD app permissions accordingly

Manual Setup (Advanced)

If you need to run the server manually:

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

# Set environment variables
export MCP_MICROSOFT_CLIENT_ID="your-client-id"
export MCP_MICROSOFT_CLIENT_SECRET="your-client-secret"
export MCP_MICROSOFT_TENANT_ID="your-tenant-id"
export MCP_MICROSOFT_SERVER_URL_OVERRIDE="https://YOUR-NGROK-URL.ngrok-free.app"

# Run server
python -m microsoft_mcp.server

Security Considerations

  • OAuth tokens are stored in memory only (cleared on restart)
  • Microsoft refresh tokens are used to maintain access
  • All API calls use secure HTTPS connections
  • Client secrets should never be committed to version control
  • Consider using Azure Key Vault for production deployments

Known Limitations

  • Only calendar tools are currently implemented
  • Tokens are stored in memory (lost on server restart)
  • Auto-registration currently hardcoded for Claude AI clients
  • Some event operations may have intermittent encoding issues

Contributing

This project is in active development. Contributions are welcome for:

  • Implementing mail, teams, and file tools
  • Improving error handling and retry logic
  • Adding comprehensive test coverage
  • Enhancing the OAuth flow security

License

[License information to be added]