Outlook MCP Server

A Model Context Protocol (MCP) server for Microsoft Outlook integration that provides comprehensive email, contact, calendar, and folder management capabilities through the Microsoft Graph API.

🚀 Quick Start

Prerequisites

• Python 3.8 or higher

• uv package manager

• Microsoft Graph API access via Nango

• Valid Outlook/Microsoft 365 account

Installation

1. Clone and setup:

   git clone <repository-url> cd outlook-mcp uv install -e .

2. Configure environment variables: Create a .env file or set these environment variables:

   NANGO_CONNECTION_ID=your_connection_id NANGO_INTEGRATION_ID=your_integration_id NANGO_BASE_URL=your_nango_base_url NANGO_SECRET_KEY=your_secret_key

3. Test the server:

   uv run python outlook_mcp_server.py --help

🔧 MCP Client Configuration

Claude Desktop Configuration

Add this to your Claude Desktop MCP configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%/Claude/claude_desktop_config.json on Windows):

Other MCP Clients

For other MCP clients, use:

• Command: uv

• Args: ["run", "python", "outlook_mcp_server.py"]

• Working Directory: Path to the outlook-mcp directory

• Transport: stdio

• Environment: Set the required Nango variables

📧 Available Tools (26 Total)

Email Management (6 tools)

• send_email - Send emails with TO/CC/BCC, HTML/text content, attachments

• create_draft_email - Create draft emails for later editing

• send_draft_email - Send existing draft emails

• get_draft_emails - Retrieve all draft emails

• update_draft_email - Modify existing draft emails

• delete_draft_email - Remove draft emails

Contact Management (5 tools)

• create_contact - Add new contacts with full details

• get_all_contacts - Retrieve all contacts

• get_contact_details - Get specific contact information

• update_contact - Modify existing contact details

• delete_contact - Remove contacts

Calendar Management (9 tools)

• get_all_calendars - List all calendars

• get_calendar_details - Get specific calendar information

• create_calendar - Create new calendars with custom colors

• update_calendar - Modify calendar properties

• delete_calendar - Remove calendars

• get_all_events - Retrieve events from calendars

• get_event_details - Get specific event information

• create_event - Schedule new events with attendees

• delete_event - Remove calendar events

Folder Management (6 tools)

• get_all_folders - List all mail folders

• get_folder_details - Get specific folder information

• create_folder - Create new mail folders (with nesting)

• update_folder - Rename folders

• delete_folder - Remove folders

• get_many_folders - Batch retrieve multiple folders

💡 Usage Examples

Send an Email

Create a Contact

Schedule a Meeting

🏗️ Project Structure

🔒 Security & Authentication

This server uses Nango for secure Microsoft Graph API authentication:

1. No direct credential storage - All auth handled by Nango

2. Token management - Automatic token refresh and management

3. Secure communication - HTTPS-only API communication

4. Environment-based config - Sensitive data in environment variables

🐛 Troubleshooting

Common Issues

1. "Missing environment variables"

   • Ensure all 4 Nango variables are set in your Claude configuration

   • Check .env file exists and is properly formatted for local development

2. "Connection failed"

   • Verify Nango integration is active

   • Check internet connectivity

   • Validate Nango credentials

3. "Tool execution failed"

   • Check Microsoft Graph API permissions

   • Verify Outlook account has necessary access

   • Review error messages in Claude Desktop logs

4. "uv command not found"

   • Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh

   • Or via pip: pip install uv

Debug Mode

For local development, run with verbose output:

Testing Connection

🧪 Development & Testing

Local Development

1. Install in development mode:

   uv install -e .

2. Run tests:

   uv run pytest tests/

3. Check tool functionality:

   uv run python -c "from outlook_mcp.tools.email import get_draft_emails; print(get_draft_emails())"

Creating Custom Tools

1. Add your tool function to the appropriate module in tools/

2. Update the server's tool list in server.py

3. Add proper input schema validation

4. Test with MCP client

📋 Requirements

• Python 3.8+

• uv >= 0.1.0 - Fast Python package installer and resolver

• mcp >= 1.0.0 - Model Context Protocol library

• requests >= 2.32.4 - HTTP client

• python-dotenv >= 1.1.1 - Environment variable management

🤝 Contributing

1. Fork the repository

2. Create a feature branch: git checkout -b feature/new-tool

3. Make your changes with tests

4. Submit a pull request

📄 License

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

🔗 Related Links

• Model Context Protocol Specification

• Microsoft Graph API Documentation

• Nango Integration Platform

• Claude Desktop MCP Configuration

• uv Package Manager

📞 Support

For issues and questions:

1. Check the troubleshooting section above

2. Review the GitHub issues

3. Create a new issue with detailed information

Built with ❤️ for seamless Outlook integration via MCP