# Outlook MCP Server
Model Context Protocol (MCP) server for Microsoft Outlook integration that enables AI assistants to interact with emails, calendar events, and contacts through Microsoft Graph API.
## Features
- **Email Management**: Read, send, and manage emails
- **Calendar Operations**: View and create calendar events
- **Contact Management**: Access and create contacts
- **Real-time Integration**: Direct connection to Microsoft Graph API
- **Secure Authentication**: Azure AD authentication support
## Components
### Resources
The server provides access to Outlook data through custom URI schemes:
- **email://**: Access email messages with metadata and content
- **calendar://**: Access calendar events with details and attendees
- **contact://**: Access contact information and details
Each resource provides structured data in JSON format with appropriate metadata.
### Tools
The server implements six powerful tools for Outlook integration:
#### Email Tools
- **get-emails**: Retrieve emails from specified folder (inbox, sent, drafts, etc.)
- Parameters: `folder` (optional, defaults to "inbox"), `limit` (optional, defaults to 10)
- Returns: List of emails with subject, sender, date, and preview
- **send-email**: Send a new email message
- Parameters: `to` (required), `subject` (required), `body` (required), `cc` (optional), `bcc` (optional)
- Returns: Confirmation with message ID
#### Calendar Tools
- **get-calendar-events**: Retrieve calendar events for a date range
- Parameters: `start_date` (optional), `end_date` (optional), `limit` (optional, defaults to 20)
- Returns: List of events with title, time, location, and attendees
- **create-calendar-event**: Create a new calendar event
- Parameters: `subject` (required), `start_time` (required), `end_time` (required), `location` (optional), `attendees` (optional), `body` (optional)
- Returns: Confirmation with event ID
#### Contact Tools
- **get-contacts**: Retrieve contacts from address book
- Parameters: `limit` (optional, defaults to 50)
- Returns: List of contacts with name, email, and phone information
- **create-contact**: Create a new contact
- Parameters: `display_name` (required), `email` (optional), `phone` (optional), `company` (optional)
- Returns: Confirmation with contact ID
### Prompts
The server provides three AI-powered prompts for enhanced productivity:
- **summarize-emails**: Generate intelligent email summaries
- Analyzes recent emails and creates structured summaries
- Identifies action items, important information, and priorities
- **schedule-summary**: Create calendar overviews
- Summarizes upcoming meetings and events
- Provides scheduling insights and conflict detection
- **compose-email**: AI-assisted email composition
- Helps draft professional emails with proper tone
- Suggests improvements and formatting
## Configuration
The server requires Azure AD app registration and configuration through environment variables:
### Required Environment Variables
```bash
# Azure AD Configuration
OUTLOOK_TENANT_ID=your-tenant-id
OUTLOOK_CLIENT_ID=your-client-id
# Choose one authentication method:
# Option 1: Client Secret (App-only authentication)
OUTLOOK_CLIENT_SECRET=your-client-secret
# Option 2: Username/Password (Delegated authentication)
OUTLOOK_USERNAME=your-username
OUTLOOK_PASSWORD=your-password
```
### Azure AD App Registration
1. Go to [Azure Portal](https://portal.azure.com) → Azure Active Directory → App registrations
2. Create a new registration with these settings:
- **Name**: Outlook MCP Server
- **Supported account types**: Accounts in this organizational directory only
- **Redirect URI**: Not required for this server type
3. Configure API permissions:
- Microsoft Graph → Application permissions (for client secret auth):
- `Mail.Read`, `Mail.Send`, `Calendars.Read`, `Calendars.ReadWrite`, `Contacts.Read`, `Contacts.ReadWrite`
- Microsoft Graph → Delegated permissions (for username/password auth):
- `Mail.Read`, `Mail.Send`, `Calendars.Read`, `Calendars.ReadWrite`, `Contacts.Read`, `Contacts.ReadWrite`
4. Grant admin consent for the permissions
5. Create a client secret (if using client secret authentication)
### Configuration File
Create a `.env` file in the project root:
```bash
cp .env.example .env
# Edit .env with your Azure AD credentials
```
## Installation & Setup
### Prerequisites
- Python 3.8 or higher
- Microsoft 365 or Outlook.com account
- Azure AD app registration (see Configuration section)
### Install from PyPI (when published)
```bash
pip install outlook-mcp
```
### Install from Source
```bash
git clone <repository-url>
cd outlook-mcp
uv sync
```
## Quickstart
### 1. Configure Environment
Set up your environment variables in `.env`:
```bash
OUTLOOK_TENANT_ID=your-tenant-id
OUTLOOK_CLIENT_ID=your-client-id
OUTLOOK_CLIENT_SECRET=your-client-secret
```
### 2. Test the Server
```bash
# Run the server directly for testing
uv run outlook-mcp
# Or test with MCP Inspector
npm install -g @modelcontextprotocol/inspector
mcp-inspector uv run outlook-mcp
```
### 3. Configure with Claude Desktop
#### Development Configuration
On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"outlook-mcp": {
"command": "uv",
"args": [
"--directory",
"/Users/annmariyajoshy/vibecoding/outlook-mcp",
"run",
"outlook-mcp"
],
"env": {
"OUTLOOK_TENANT_ID": "your-tenant-id",
"OUTLOOK_CLIENT_ID": "your-client-id",
"OUTLOOK_CLIENT_SECRET": "your-client-secret"
}
}
}
}
```
#### Production Configuration (when published)
```json
{
"mcpServers": {
"outlook-mcp": {
"command": "uvx",
"args": ["outlook-mcp"],
"env": {
"OUTLOOK_TENANT_ID": "your-tenant-id",
"OUTLOOK_CLIENT_ID": "your-client-id",
"OUTLOOK_CLIENT_SECRET": "your-client-secret"
}
}
}
}
```
## Usage Examples
### Email Operations
```python
# Get recent emails
emails = await get_emails(folder="inbox", limit=5)
# Send an email
await send_email(
to="recipient@example.com",
subject="Hello from MCP",
body="This email was sent through the MCP server!"
)
```
### Calendar Operations
```python
# Get upcoming events
events = await get_calendar_events(
start_date="2024-01-01",
end_date="2024-01-31"
)
# Create a meeting
await create_calendar_event(
subject="Team Standup",
start_time="2024-01-15T09:00:00",
end_time="2024-01-15T09:30:00",
attendees=["team@example.com"]
)
```
### Contact Operations
```python
# Get contacts
contacts = await get_contacts(limit=10)
# Create a contact
await create_contact(
display_name="John Doe",
email="john.doe@example.com",
phone="+1-555-123-4567"
)
```
## Error Handling
The server includes comprehensive error handling for common scenarios:
- **Authentication failures**: Clear error messages for expired tokens or invalid credentials
- **Permission errors**: Helpful guidance when API permissions are insufficient
- **Rate limiting**: Automatic retry logic with exponential backoff
- **Network issues**: Graceful degradation and error reporting
## Security Considerations
- **Credential Storage**: Never commit credentials to version control
- **Token Management**: Tokens are handled securely by Azure Identity library
- **Scope Limitation**: Request only necessary permissions for your use case
- **Network Security**: All communication uses HTTPS with Microsoft Graph API
## Troubleshooting
### Common Issues
1. **Authentication Error**: Verify your tenant ID, client ID, and credentials
2. **Permission Denied**: Check that required permissions are granted and admin consented
3. **Module Not Found**: Ensure all dependencies are installed with `uv sync`
4. **Rate Limiting**: Implement delays between requests if hitting API limits
### Debug Mode
Enable detailed logging:
```bash
export PYTHONPATH=/path/to/outlook-mcp/src
export MCP_LOG_LEVEL=DEBUG
uv run outlook-mcp
```
### MCP Inspector
For advanced debugging, use the MCP Inspector:
```bash
npm install -g @modelcontextprotocol/inspector
mcp-inspector uv run outlook-mcp
```
## Development
### Building and Publishing
To prepare the package for distribution:
1. Sync dependencies and update lockfile:
```bash
uv sync
```
2. Build package distributions:
```bash
uv build
```
This will create source and wheel distributions in the `dist/` directory.
3. Publish to PyPI:
```bash
uv publish
```
Note: You'll need to set PyPI credentials via environment variables or command flags:
- Token: `--token` or `UV_PUBLISH_TOKEN`
- Or username/password: `--username`/`UV_PUBLISH_USERNAME` and `--password`/`UV_PUBLISH_PASSWORD`
### Debugging
Since MCP servers run over stdio, debugging can be challenging. For the best debugging
experience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:
```bash
npx @modelcontextprotocol/inspector uv --directory /Users/annmariyajoshy/vibecoding/outlook-mcp run outlook-mcp
```
Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
Raw data
{
"_id": null,
"home_page": null,
"name": "outlook-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "ai, assistant, calendar, contacts, email, graph, mcp, microsoft, outlook",
"author": null,
"author_email": "akhilthomas236 <akhilthomas236@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/59/58/3ee36ebd16a786e456068868e4c358f91b2be8fbb9da56899db65a0eadd3/outlook_mcp-0.1.0.tar.gz",
"platform": null,
"description": "# Outlook MCP Server\n\nModel Context Protocol (MCP) server for Microsoft Outlook integration that enables AI assistants to interact with emails, calendar events, and contacts through Microsoft Graph API.\n\n## Features\n\n- **Email Management**: Read, send, and manage emails\n- **Calendar Operations**: View and create calendar events\n- **Contact Management**: Access and create contacts\n- **Real-time Integration**: Direct connection to Microsoft Graph API\n- **Secure Authentication**: Azure AD authentication support\n\n## Components\n\n### Resources\n\nThe server provides access to Outlook data through custom URI schemes:\n\n- **email://**: Access email messages with metadata and content\n- **calendar://**: Access calendar events with details and attendees \n- **contact://**: Access contact information and details\n\nEach resource provides structured data in JSON format with appropriate metadata.\n\n### Tools\n\nThe server implements six powerful tools for Outlook integration:\n\n#### Email Tools\n- **get-emails**: Retrieve emails from specified folder (inbox, sent, drafts, etc.)\n - Parameters: `folder` (optional, defaults to \"inbox\"), `limit` (optional, defaults to 10)\n - Returns: List of emails with subject, sender, date, and preview\n\n- **send-email**: Send a new email message\n - Parameters: `to` (required), `subject` (required), `body` (required), `cc` (optional), `bcc` (optional)\n - Returns: Confirmation with message ID\n\n#### Calendar Tools \n- **get-calendar-events**: Retrieve calendar events for a date range\n - Parameters: `start_date` (optional), `end_date` (optional), `limit` (optional, defaults to 20)\n - Returns: List of events with title, time, location, and attendees\n\n- **create-calendar-event**: Create a new calendar event\n - Parameters: `subject` (required), `start_time` (required), `end_time` (required), `location` (optional), `attendees` (optional), `body` (optional)\n - Returns: Confirmation with event ID\n\n#### Contact Tools\n- **get-contacts**: Retrieve contacts from address book\n - Parameters: `limit` (optional, defaults to 50)\n - Returns: List of contacts with name, email, and phone information\n\n- **create-contact**: Create a new contact\n - Parameters: `display_name` (required), `email` (optional), `phone` (optional), `company` (optional)\n - Returns: Confirmation with contact ID\n\n### Prompts\n\nThe server provides three AI-powered prompts for enhanced productivity:\n\n- **summarize-emails**: Generate intelligent email summaries\n - Analyzes recent emails and creates structured summaries\n - Identifies action items, important information, and priorities\n\n- **schedule-summary**: Create calendar overviews \n - Summarizes upcoming meetings and events\n - Provides scheduling insights and conflict detection\n\n- **compose-email**: AI-assisted email composition\n - Helps draft professional emails with proper tone\n - Suggests improvements and formatting\n\n## Configuration\n\nThe server requires Azure AD app registration and configuration through environment variables:\n\n### Required Environment Variables\n\n```bash\n# Azure AD Configuration\nOUTLOOK_TENANT_ID=your-tenant-id\nOUTLOOK_CLIENT_ID=your-client-id\n\n# Choose one authentication method:\n# Option 1: Client Secret (App-only authentication)\nOUTLOOK_CLIENT_SECRET=your-client-secret\n\n# Option 2: Username/Password (Delegated authentication) \nOUTLOOK_USERNAME=your-username\nOUTLOOK_PASSWORD=your-password\n```\n\n### Azure AD App Registration\n\n1. Go to [Azure Portal](https://portal.azure.com) \u2192 Azure Active Directory \u2192 App registrations\n2. Create a new registration with these settings:\n - **Name**: Outlook MCP Server\n - **Supported account types**: Accounts in this organizational directory only\n - **Redirect URI**: Not required for this server type\n\n3. Configure API permissions:\n - Microsoft Graph \u2192 Application permissions (for client secret auth):\n - `Mail.Read`, `Mail.Send`, `Calendars.Read`, `Calendars.ReadWrite`, `Contacts.Read`, `Contacts.ReadWrite`\n - Microsoft Graph \u2192 Delegated permissions (for username/password auth):\n - `Mail.Read`, `Mail.Send`, `Calendars.Read`, `Calendars.ReadWrite`, `Contacts.Read`, `Contacts.ReadWrite`\n\n4. Grant admin consent for the permissions\n5. Create a client secret (if using client secret authentication)\n\n### Configuration File\n\nCreate a `.env` file in the project root:\n\n```bash\ncp .env.example .env\n# Edit .env with your Azure AD credentials\n```\n\n## Installation & Setup\n\n### Prerequisites\n\n- Python 3.8 or higher\n- Microsoft 365 or Outlook.com account\n- Azure AD app registration (see Configuration section)\n\n### Install from PyPI (when published)\n\n```bash\npip install outlook-mcp\n```\n\n### Install from Source\n\n```bash\ngit clone <repository-url>\ncd outlook-mcp\nuv sync\n```\n\n## Quickstart\n\n### 1. Configure Environment\n\nSet up your environment variables in `.env`:\n\n```bash\nOUTLOOK_TENANT_ID=your-tenant-id\nOUTLOOK_CLIENT_ID=your-client-id\nOUTLOOK_CLIENT_SECRET=your-client-secret\n```\n\n### 2. Test the Server\n\n```bash\n# Run the server directly for testing\nuv run outlook-mcp\n\n# Or test with MCP Inspector\nnpm install -g @modelcontextprotocol/inspector\nmcp-inspector uv run outlook-mcp\n```\n\n### 3. Configure with Claude Desktop\n\n#### Development Configuration\n\nOn MacOS: `~/Library/Application\\ Support/Claude/claude_desktop_config.json`\nOn Windows: `%APPDATA%/Claude/claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"outlook-mcp\": {\n \"command\": \"uv\",\n \"args\": [\n \"--directory\",\n \"/Users/annmariyajoshy/vibecoding/outlook-mcp\",\n \"run\",\n \"outlook-mcp\"\n ],\n \"env\": {\n \"OUTLOOK_TENANT_ID\": \"your-tenant-id\",\n \"OUTLOOK_CLIENT_ID\": \"your-client-id\", \n \"OUTLOOK_CLIENT_SECRET\": \"your-client-secret\"\n }\n }\n }\n}\n```\n\n#### Production Configuration (when published)\n\n```json\n{\n \"mcpServers\": {\n \"outlook-mcp\": {\n \"command\": \"uvx\",\n \"args\": [\"outlook-mcp\"],\n \"env\": {\n \"OUTLOOK_TENANT_ID\": \"your-tenant-id\",\n \"OUTLOOK_CLIENT_ID\": \"your-client-id\",\n \"OUTLOOK_CLIENT_SECRET\": \"your-client-secret\"\n }\n }\n }\n}\n```\n\n## Usage Examples\n\n### Email Operations\n\n```python\n# Get recent emails\nemails = await get_emails(folder=\"inbox\", limit=5)\n\n# Send an email\nawait send_email(\n to=\"recipient@example.com\",\n subject=\"Hello from MCP\",\n body=\"This email was sent through the MCP server!\"\n)\n```\n\n### Calendar Operations\n\n```python\n# Get upcoming events\nevents = await get_calendar_events(\n start_date=\"2024-01-01\",\n end_date=\"2024-01-31\"\n)\n\n# Create a meeting\nawait create_calendar_event(\n subject=\"Team Standup\",\n start_time=\"2024-01-15T09:00:00\",\n end_time=\"2024-01-15T09:30:00\",\n attendees=[\"team@example.com\"]\n)\n```\n\n### Contact Operations\n\n```python\n# Get contacts\ncontacts = await get_contacts(limit=10)\n\n# Create a contact\nawait create_contact(\n display_name=\"John Doe\",\n email=\"john.doe@example.com\",\n phone=\"+1-555-123-4567\"\n)\n```\n\n## Error Handling\n\nThe server includes comprehensive error handling for common scenarios:\n\n- **Authentication failures**: Clear error messages for expired tokens or invalid credentials\n- **Permission errors**: Helpful guidance when API permissions are insufficient \n- **Rate limiting**: Automatic retry logic with exponential backoff\n- **Network issues**: Graceful degradation and error reporting\n\n## Security Considerations\n\n- **Credential Storage**: Never commit credentials to version control\n- **Token Management**: Tokens are handled securely by Azure Identity library\n- **Scope Limitation**: Request only necessary permissions for your use case\n- **Network Security**: All communication uses HTTPS with Microsoft Graph API\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Authentication Error**: Verify your tenant ID, client ID, and credentials\n2. **Permission Denied**: Check that required permissions are granted and admin consented\n3. **Module Not Found**: Ensure all dependencies are installed with `uv sync`\n4. **Rate Limiting**: Implement delays between requests if hitting API limits\n\n### Debug Mode\n\nEnable detailed logging:\n\n```bash\nexport PYTHONPATH=/path/to/outlook-mcp/src\nexport MCP_LOG_LEVEL=DEBUG\nuv run outlook-mcp\n```\n\n### MCP Inspector\n\nFor advanced debugging, use the MCP Inspector:\n\n```bash\nnpm install -g @modelcontextprotocol/inspector\nmcp-inspector uv run outlook-mcp\n```\n\n## Development\n\n### Building and Publishing\n\nTo prepare the package for distribution:\n\n1. Sync dependencies and update lockfile:\n```bash\nuv sync\n```\n\n2. Build package distributions:\n```bash\nuv build\n```\n\nThis will create source and wheel distributions in the `dist/` directory.\n\n3. Publish to PyPI:\n```bash\nuv publish\n```\n\nNote: You'll need to set PyPI credentials via environment variables or command flags:\n- Token: `--token` or `UV_PUBLISH_TOKEN`\n- Or username/password: `--username`/`UV_PUBLISH_USERNAME` and `--password`/`UV_PUBLISH_PASSWORD`\n\n### Debugging\n\nSince MCP servers run over stdio, debugging can be challenging. For the best debugging\nexperience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).\n\n\nYou can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:\n\n```bash\nnpx @modelcontextprotocol/inspector uv --directory /Users/annmariyajoshy/vibecoding/outlook-mcp run outlook-mcp\n```\n\n\nUpon launching, the Inspector will display a URL that you can access in your browser to begin debugging.",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for Microsoft Outlook integration to manage emails, calendar events, and contacts",
"version": "0.1.0",
"project_urls": {
"Bug Reports": "https://github.com/akhilthomas236/outlook-mcp/issues",
"Documentation": "https://github.com/akhilthomas236/outlook-mcp#readme",
"Homepage": "https://github.com/akhilthomas236/outlook-mcp",
"Repository": "https://github.com/akhilthomas236/outlook-mcp"
},
"split_keywords": [
"ai",
" assistant",
" calendar",
" contacts",
" email",
" graph",
" mcp",
" microsoft",
" outlook"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5fac8ff387e79ce9d629ea4c34f2392905288d2267b41cf3765e859ac53791f2",
"md5": "8514996f9423a10c2d169ffe4622bfa8",
"sha256": "0965efcc5f3052fc93646dcbc5d40e5b6a21947f718294fc2894aa9f4f5fdba5"
},
"downloads": -1,
"filename": "outlook_mcp-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8514996f9423a10c2d169ffe4622bfa8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 20603,
"upload_time": "2025-07-19T11:13:57",
"upload_time_iso_8601": "2025-07-19T11:13:57.226833Z",
"url": "https://files.pythonhosted.org/packages/5f/ac/8ff387e79ce9d629ea4c34f2392905288d2267b41cf3765e859ac53791f2/outlook_mcp-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "59583ee36ebd16a786e456068868e4c358f91b2be8fbb9da56899db65a0eadd3",
"md5": "4483f6e13ff523d19169b1e270b603e5",
"sha256": "e15c19c0f2d72b210ce3c92f290f72cf7283d690f0e9cc7a97c5a8086f278816"
},
"downloads": -1,
"filename": "outlook_mcp-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "4483f6e13ff523d19169b1e270b603e5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 80910,
"upload_time": "2025-07-19T11:13:59",
"upload_time_iso_8601": "2025-07-19T11:13:59.285074Z",
"url": "https://files.pythonhosted.org/packages/59/58/3ee36ebd16a786e456068868e4c358f91b2be8fbb9da56899db65a0eadd3/outlook_mcp-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-19 11:13:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "akhilthomas236",
"github_project": "outlook-mcp",
"github_not_found": true,
"lcname": "outlook-mcp"
}
JSON
