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
-
Clone and setup:
git clone <repository-url> cd outlook-mcp uv install -e . -
Configure environment variables: Create a
.envfile 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 -
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, attachmentscreate_draft_email- Create draft emails for later editingsend_draft_email- Send existing draft emailsget_draft_emails- Retrieve all draft emailsupdate_draft_email- Modify existing draft emailsdelete_draft_email- Remove draft emails
Contact Management (5 tools)
create_contact- Add new contacts with full detailsget_all_contacts- Retrieve all contactsget_contact_details- Get specific contact informationupdate_contact- Modify existing contact detailsdelete_contact- Remove contacts
Calendar Management (9 tools)
get_all_calendars- List all calendarsget_calendar_details- Get specific calendar informationcreate_calendar- Create new calendars with custom colorsupdate_calendar- Modify calendar propertiesdelete_calendar- Remove calendarsget_all_events- Retrieve events from calendarsget_event_details- Get specific event informationcreate_event- Schedule new events with attendeesdelete_event- Remove calendar events
Folder Management (6 tools)
get_all_folders- List all mail foldersget_folder_details- Get specific folder informationcreate_folder- Create new mail folders (with nesting)update_folder- Rename foldersdelete_folder- Remove foldersget_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:
- No direct credential storage - All auth handled by Nango
- Token management - Automatic token refresh and management
- Secure communication - HTTPS-only API communication
- Environment-based config - Sensitive data in environment variables
🐛 Troubleshooting
Common Issues
-
"Missing environment variables"
- Ensure all 4 Nango variables are set in your Claude configuration
- Check
.envfile exists and is properly formatted for local development
-
"Connection failed"
- Verify Nango integration is active
- Check internet connectivity
- Validate Nango credentials
-
"Tool execution failed"
- Check Microsoft Graph API permissions
- Verify Outlook account has necessary access
- Review error messages in Claude Desktop logs
-
"uv command not found"
- Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh - Or via pip:
pip install uv
- 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
-
Install in development mode:
uv install -e . -
Run tests:
uv run pytest tests/ -
Check tool functionality:
uv run python -c "from outlook_mcp.tools.email import get_draft_emails; print(get_draft_emails())"
Creating Custom Tools
- Add your tool function to the appropriate module in
tools/ - Update the server's tool list in
server.py - Add proper input schema validation
- 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
- Fork the repository
- Create a feature branch:
git checkout -b feature/new-tool - Make your changes with tests
- 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:
- Check the troubleshooting section above
- Review the GitHub issues
- Create a new issue with detailed information
Built with ❤️ for seamless Outlook integration via MCP