outlook-mcp
If you are the rightful owner of outlook-mcp 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@mcpreview.com.
This is a modular implementation of the Outlook MCP server that connects Claude with Microsoft Outlook through the Microsoft Graph API.
Modular Outlook MCP Server
This is a modular implementation of the Outlook MCP (Model Context Protocol) server that connects Claude with Microsoft Outlook through the Microsoft Graph API.
Directory Structure
/modular/
āāā index.js # Main entry point
āāā config.js # Configuration settings
āāā auth/ # Authentication modules
ā āāā index.js # Authentication exports
ā āāā token-manager.js # Token storage and refresh
ā āāā tools.js # Auth-related tools
āāā calendar/ # Calendar functionality
ā āāā index.js # Calendar exports
ā āāā list.js # List events
ā āāā create.js # Create event
ā āāā delete.js # Delete event
ā āāā cancel.js # Cancel
ā āāā accept.js # Accept event
ā āāā tentative.js # Tentatively accept event
ā āāā decline.js # Decline event
āāā email/ # Email functionality
ā āāā index.js # Email exports
ā āāā list.js # List emails
ā āāā search.js # Search emails
ā āāā read.js # Read email
ā āāā send.js # Send email
āāā utils/ # Utility functions
āāā graph-api.js # Microsoft Graph API helper
āāā odata-helpers.js # OData query building
āāā mock-data.js # Test mode data
Features
- Authentication: OAuth 2.0 authentication with Microsoft Graph API
- Email Management: List, search, read, and send emails
- Modular Structure: Clean separation of concerns for better maintainability
- OData Filter Handling: Proper escaping and formatting of OData queries
- Test Mode: Simulated responses for testing without real API calls
Azure App Registration & Configuration
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.
App Registration
- 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
App Permissions
- 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"
Client Secret
- 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
Configuration
To configure the server, edit the config.js
file to change:
- Server name and version
- Test mode settings
- Authentication parameters
- Email field selections
- API endpoints
Usage with Claude Desktop
- 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
Running Standalone
You can test the server using:
./test-modular-server.sh
This will use the MCP Inspector to directly connect to the server and let you test the available tools.
Authentication Flow
- 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
Troubleshooting
- Authentication Issues: Check the token file and authentication server logs
- OData Filter Errors: Look for escape sequences in the server logs
- API Call Failures: Check for detailed error messages in the response
Extending the Server
To add more functionality:
- Create new module directories (e.g.,
calendar/
) - Implement tool handlers in separate files
- Export tool definitions from module index files
- Import and add tools to
TOOLS
array inindex.js