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):

{
  "mcpServers": {
    "outlook": {
      "command": "uvx",
      "args": [
        "git+https://github.com/ampcome-mcps/outlook-mcp.git",
      ],
      "env": {
        "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"
      }
    }
  }
}

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

{
  "tool": "send_email",
  "arguments": {
    "subject": "Project Update",
    "content": "<h1>Hello!</h1><p>Here's the latest update...</p>",
    "to_recipients": ["colleague@company.com"],
    "cc_recipients": ["manager@company.com"],
    "importance": "high"
  }
}

Create a Contact

{
  "tool": "create_contact",
  "arguments": {
    "given_name": "John",
    "surname": "Doe",
    "email_addresses": "john.doe@company.com,john@personal.com",
    "company_name": "Acme Corp",
    "job_title": "Software Engineer"
  }
}

Schedule a Meeting

{
  "tool": "create_event",
  "arguments": {
    "subject": "Weekly Team Meeting",
    "start_datetime": "2024-01-15T10:00:00",
    "end_datetime": "2024-01-15T11:00:00",
    "attendees": ["team@company.com"],
    "location": "Conference Room A",
    "body_content": "Discussing project milestones"
  }
}

🏗️ Project Structure

outlook-mcp/
├── src/outlook_mcp/
│   ├── __init__.py
│   ├── server.py              # Main MCP server implementation
│   ├── connection.py          # Nango API connection handling
│   └── tools/
│       ├── __init__.py
│       ├── email.py           # Email management tools
│       ├── contacts.py        # Contact management tools
│       ├── calendar.py        # Calendar and event tools
│       └── folders.py         # Folder management tools
├── outlook_mcp_server.py      # Standalone server entry point
├── main.py                    # Alternative entry point
├── pyproject.toml            # Package configuration with uv
├── uv.lock                   # uv lockfile for reproducible builds
├── README.md                 # This documentation
└── .env                      # Environment variables (create this)

🔒 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:

uv run python outlook_mcp_server.py 2>debug.log

Testing Connection

uv run python -c "from outlook_mcp.connection import get_access_token; print('✅ Connection successful!' if get_access_token() else '❌ Connection failed')"

🧪 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