A Python-based Microsoft Outlook integration using Microsoft Graph API, built with FastAPI and MCP framework.
This project provides a server implementation for Microsoft Outlook integration using the Microsoft Graph API. It includes authentication handling, mail operations, and various utility functions for working with Outlook data.
- Microsoft Graph API integration
- OAuth2 authentication flow
- Mail operations (send, read, manage)
- FastAPI-based server implementation
- Environment-based configuration
- Logging functionality
auth/
- Authentication related modulesmail/
- Mail operation modulesutils/
- Utility functionsmain.py
- Main application entry pointserver.py
- Server configurationconfig.py
- Configuration settingslogger.py
- Logging configurationoutlook_auth_server.py
- Outlook authentication server implementation
- Python 3.8 or higher
- Microsoft Azure account with registered application
- Microsoft Graph API access
- Clone the repository:
git clone [repository-url]
cd mcp-outlook-python
- Create and activate a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
- Install dependencies:
pip install -r requirements.txt
To use this MCP server you need to first register and configure an app in Azure Portal. The following steps will take you through the process of registering a new app, configuring its permissions, and generating a client secret.
- Open Azure Portal in your browser
- Sign in with a Microsoft Work or Personal account
- Search for or cilck on "App registrations"
- Click on "New registration"
- Enter a name for the app, for example "Outlook MCP Server"
- Select the "Accounts in any organizational directory and personal Microsoft accounts" option
- In the "Redirect URI" section, select "Web" from the dropdown and enter "http://localhost:3333/auth/callback" in the textbox
- Click on "Register"
- From the Overview section of the app settings page, copy the "Application (client) ID" and enter it as the MS_CLIENT_ID in the .env file as well as the OUTLOOK_CLIENT_ID in the claude-config-sample.json file
- From the app settings page in Azure Portal select the "API permissions" option under the Manage section
- Click on "Add a permission"
- Click on "Microsoft Graph"
- Select "Delegated permissions"
- Search for the following permissions and slect the checkbox next to each one
- offline_access
- User.Read
- Mail.Read
- Mail.Send
- Calendars.Read
- Calendars.ReadWrite
- Contacts.Read
- Click on "Add permissions"
- From the app settings page in Azure Portal select the "Certificates & secrets" option under the Manage section
- Switch to the "Client secrets" tab
- Click on "New client secret"
- Enter a description, for example "Client Secret"
- Select the longest possible expiration time
- Click on "Add"
- Copy the secret value and enter it as the MS_CLIENT_SECRET in the .env file as well as the OUTLOOK_CLIENT_SECRET in the claude-config-sample.json file
- Create a
.env
file in the root directory with the following variables:
MS_CLIENT_ID=your-ms-client-id
MS_CLIENT_SECRET=your-ms-client-secret
MS_AUTH_SERVER_URL=your-ms-auth-server-url
- Update the configuration in
config.py
as needed.
- Copy the sample configuration from
claude-config-sample.json
to your Claude Desktop configuration - Restart Claude Desktop
- Authenticate with Microsoft using the
authenticate
tool - Use the email tools to manage your Outlook account
- Start a local authentication server on port 3333 (using
outlook-auth-server.js
) - Use the
authenticate
tool to get an authentication URL - Complete the authentication in your browser
- Tokens are stored in
~/.outlook-mcp-tokens.json
- Authentication Issues: Check the token file and authentication server logs
- API Call Failures: Check for detailed error messages in the response
- fastapi
- uvicorn
- python-dotenv
- pydantic
- pydantic-settings
- requests
- aiohttp
- mcp