Outlook MCP Server


A Model Context Protocol (MCP) server that provides read-only access to Outlook for Mac. Access your emails, calendar events, contacts, tasks, and notes directly through MCP tools.

Features

- Mostly read-only - Calendar event creation supported; all other data is read-only
- Two backends - AppleScript for classic Outlook, Microsoft Graph API for new Outlook
- Works offline - AppleScript backend requires no network (Graph API requires internet)
- Fast and reliable - Direct communication with Outlook or Microsoft servers

$3

Accounts
- list_accounts - List all configured Outlook accounts

Mail
- list_folders - List all mail folders with unread counts (supports account_id filtering)
- list_emails - List emails in a folder with pagination
- search_emails - Search emails by subject, sender, or content
- get_email - Get full email details including body
- get_unread_count - Get unread email count
- send_email - Send an email with attachments and HTML support (AppleScript backend only)

Calendar
- list_calendars - List all calendars
- list_events - List events with date range filtering
- get_event - Get event details
- search_events - Search events by title
- create_event - Create a new calendar event (AppleScript backend only)
- respond_to_event - Accept, decline, or tentatively accept event invitations (AppleScript backend only)
- delete_event - Delete a calendar event or recurring series (AppleScript backend only)
- update_event - Update event details (title, time, location, etc.) (AppleScript backend only)

Contacts
- list_contacts - List all contacts with pagination
- search_contacts - Search contacts by name
- get_contact - Get contact details

Tasks
- list_tasks - List tasks with completion filtering
- get_task - Get task details
- search_tasks - Search tasks by name

Notes
- list_notes - List all notes
- get_note - Get note details
- search_notes - Search notes by content

> Note: Notes are only supported with the AppleScript backend. Microsoft Graph API does not provide access to Outlook Notes.

🚀 Quick Start

$3

``bash
npx -y mcp-outlook-mac
`
Requires: Classic Outlook for Mac running

$3

`bash

Uses shared Azure AD app - works out of the box

npx -y mcp-outlook-mac
`
Set USE_GRAPH_API=1 in your MCP configuration.

On first run, complete device code authentication. See Configuration for details.

For production or work accounts: See Custom Azure AD Setup below.

Known Limitations

$3

Google Accounts Not Supported

Google accounts configured in Outlook for Mac cannot be accessed via the AppleScript backend. This is a macOS/Outlook limitation - Google accounts use a proprietary OAuth integration that isn't exposed through AppleScript.

Supported account types:
- Exchange accounts
- IMAP accounts
- POP accounts

Not supported:
- Google accounts (native integration)

Workarounds:
1. Configure Google as an IMAP account instead of using the native Google integration
2. Use the Graph API backend (USE_GRAPH_API=1) which has different account handling

Write Operations

Currently, write operations (event management, email sending) are only supported via the AppleScript backend. These features will be added to the Graph API backend in a future release:
- Event RSVP operations
- Event deletion
- Event updates
- Email sending

For these operations, use the AppleScript backend with classic Outlook for Mac.

$3

🚧 Beta Status

The Graph API backend is currently in beta. Write operations are not yet implemented:
- ❌ Event management (create, update, delete, RSVP) - Coming soon
- ❌ Email sending - Coming soon
- ✅ All read operations are fully functional and stable

Notes Not Available

Microsoft Graph API does not provide access to Outlook Notes. If you need access to notes, use the AppleScript backend.

Backends

$3

The default backend uses AppleScript to communicate with Microsoft Outlook for Mac. This works best with classic Outlook and requires Outlook to be running.

$3

For "new Outlook" for Mac (cloud-based), use the Microsoft Graph API backend. This connects directly to Microsoft's servers and doesn't require Outlook to be running.

To enable the Graph API backend, set the environment variable:

`bash
USE_GRAPH_API=1
`

#### First-Time Authentication

When using the Graph API backend for the first time, you'll need to authenticate:

1. The server will display a device code and URL
2. Visit https://microsoft.com/devicelogin
3. Enter the code displayed in the terminal
4. Sign in with your Microsoft account
5. Grant the requested permissions

Your authentication tokens are stored securely in ~/.outlook-mcp/tokens.json and will be refreshed automatically.

#### Required Permissions

The Graph API backend requests these Microsoft Graph permissions:
- Mail.ReadWrite - Read and send your mail
- Calendars.ReadWrite - Read and manage your calendars
- Contacts.Read - Read your contacts
- Tasks.Read - Read your tasks
- User.Read - Read your profile
- offline_access - Maintain access (for token refresh)

Note: Write operations (email sending, event management) are configured but not yet implemented in the Graph API backend. They currently only work via the AppleScript backend.

#### Security Model - Shared Azure AD App

This project provides a shared Azure AD application for quick-start convenience. Here's what you should know:

##### ✅ What the Shared App CAN Access

- Only data you explicitly consent to during the device code authentication flow
- Only when you're actively using the MCP server
- Tokens are stored locally on your machine (~/.outlook-mcp/tokens.json)
- Read-only access to mail, calendar, contacts, and tasks

##### ❌ What the Shared App CANNOT Access

- Your data when you're not using the server - tokens are only used by your local MCP instance
- Your password or credentials - Microsoft handles authentication
- Other users' data - each user authenticates separately with their own account
- Write operations - current permissions are read-only (by design)

##### 🔒 How It Works (Technical Details)

`
Your Device → Shared Azure App ID → Microsoft Authentication
↓
Your Microsoft Account
↓
Access Token (stored locally)
↓
Microsoft Graph API → Your Data
`

Key Security Points:
- The Azure AD client ID is public (not a secret) - it's just an identifier
- You authenticate with your own Microsoft account - the app owner never sees your credentials
- Access tokens are issued to you and stored on your machine - the app owner cannot access them
- Delegated permissions mean the app can only act on your behalf when you're using it
- Open source code - you can audit exactly what the server does with your data

##### 🏢 For Production or Corporate Use

We recommend creating your own Azure AD app if:
- You're using a work/school account with conditional access policies
- Your organization requires internal app registrations only
- You want full control over the app lifecycle
- You need audit logs under your tenant

See Custom Azure AD Setup below for instructions.

##### 🤝 Trust & Transparency

- ✅ Open Source - Full code available at GitHub
- ✅ Minimal Scopes - Only requests necessary read permissions
- ✅ Standard Practice - Same model used by Postman, Microsoft Graph Explorer, and many open-source tools
- ✅ User Control - You can revoke access anytime in your Microsoft account settings
- ✅ Override Option - Use OUTLOOK_MCP_CLIENT_ID environment variable to use your own app

##### ⚠️ Shared App Considerations

Potential limitations:
- If the shared app is revoked or deleted, you'll need to use your own app
- All users share the app's rate limits (10,000 requests per 10 minutes - sufficient for typical use)
- Corporate policies may block external multi-tenant apps

Risk to app owner (JBC Tech Solutions):
- Microsoft could revoke the app if abuse is detected (minimal risk with read-only permissions)
- No access to your data or liability for your usage

Cost: Using the shared app is free for everyone - no charges to you or the app owner.

$3

The server includes a pre-configured shared Azure AD app for quick-start testing. For production use, custom deployments, or work/school accounts with conditional access, create your own:

#### 1. Register Azure AD Application

1. Go to Azure Portal → Azure Active Directory → App registrations → New registration
2. Name: Outlook MCP Server
3. Supported account types: "Accounts in any organizational directory and personal Microsoft accounts (Multitenant)"
4. Redirect URI: Leave blank
5. Click Register
6. Note the Application (client) ID

#### 2. Configure Permissions

1. Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions
2. Add these permissions:
- Mail.ReadWrite - Read and send mail
- Calendars.ReadWrite - Manage calendar events
- Contacts.Read - Read contacts
- Tasks.Read - Read tasks
- User.Read - User profile
- offline_access - Token refresh
3. Click Add permissions

#### 3. Enable Public Client Flow

1. Go to Authentication
2. Advanced settings → Allow public client flows → Yes
3. Click Save

#### 4. Configure Environment

`json
{
"mcpServers": {
"outlook-mac": {
"command": "npx",
"args": ["-y", "mcp-outlook-mac"],
"env": {
"USE_GRAPH_API": "1",
"OUTLOOK_MCP_CLIENT_ID": "your-client-id-here",
"OUTLOOK_MCP_TENANT_ID": "common"
}
}
}
}
`

#### Tenant Options
- common - Multi-tenant (personal, work, school accounts)
- organizations - Work/school accounts only
- consumers - Personal Microsoft accounts only
- {tenant-id} - Specific Azure AD tenant

#### Trade-offs

| Approach | Pros | Cons |
|----------|------|------|
| Shared App | Zero setup, works immediately | Shared with others, may not work with conditional access |
| Custom App | Full control, works with conditional access, audit logs | Requires Azure AD setup |

Cost: Both options are free - Azure AD Free tier is sufficient.

Installation

$3

`bash
npx -y @jbctechsolutions/mcp-outlook-mac
`

$3

`bash
npm install -g @jbctechsolutions/mcp-outlook-mac
`

Configuration

$3

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

AppleScript backend (default):
`json
{
"mcpServers": {
"outlook-mac": {
"command": "npx",
"args": ["-y", "@jbctechsolutions/mcp-outlook-mac"]
}
}
}
`

Graph API backend (for new Outlook):
`json
{
"mcpServers": {
"outlook-mac": {
"command": "npx",
"args": ["-y", "@jbctechsolutions/mcp-outlook-mac"],
"env": {
"USE_GRAPH_API": "1"
}
}
}
}
`

$3

#### Option 1: Install as Plugin (Recommended)

Add the plugin marketplace to your ~/.claude/settings.json:

`json
{
"extraKnownMarketplaces": {
"jbctechsolutions": {
"source": {
"source": "github",
"repo": "jbctechsolutions/mcp-outlook-mac"
}
}
},
"enabledPlugins": {
"outlook-mac@jbctechsolutions": true
}
}
`

#### Option 2: Manual Configuration

Project-specific - Add .mcp.json to your project:
`json
{
"mcpServers": {
"outlook-mac": {
"command": "npx",
"args": ["-y", "@jbctechsolutions/mcp-outlook-mac"]
}
}
}
`

Global - Create ~/.claude/.mcp.json:
`json
{
"mcpServers": {
"outlook-mac": {
"command": "npx",
"args": ["-y", "@jbctechsolutions/mcp-outlook-mac"]
}
}
}
`

Graph API backend (for new Outlook):
`json
{
"mcpServers": {
"outlook-mac": {
"command": "npx",
"args": ["-y", "@jbctechsolutions/mcp-outlook-mac"],
"env": {
"USE_GRAPH_API": "1"
}
}
}
}
`

Requirements

$3

- macOS
- Microsoft Outlook for Mac (must be running when using tools)
- Node.js 18 or later
- Automation permission for Outlook (you'll be prompted on first use)

$3

- macOS, Windows, or Linux
- Microsoft account (personal or work/school)
- Node.js 18 or later
- Internet connection

Permissions

$3

The MCP server communicates with Outlook via AppleScript. On first use, you'll be prompted to grant automation permission. You can also configure this in:

System Settings > Privacy & Security > Automation

Make sure your terminal or Claude Desktop is allowed to control Microsoft Outlook.

$3

The Graph API backend requires you to sign in with your Microsoft account and grant permissions to read your mail, calendar, contacts, and tasks. See the First-Time Authentication section above.

Troubleshooting

$3

#### Outlook not running

The server requires Outlook to be running. Start Microsoft Outlook before using the MCP tools.

#### Permission denied

If you see an automation permission error:

1. Open System Settings > Privacy & Security > Automation
2. Find your terminal app or Claude Desktop
3. Enable the toggle for Microsoft Outlook

#### Timeout errors

Large mailboxes may cause timeout errors. Try reducing the limit parameter in your queries.

$3

#### Authentication required

If you see "Microsoft Graph authentication required", you need to complete the device code flow:

1. Look for the device code in the terminal output
2. Visit https://microsoft.com/devicelogin
3. Enter the code and sign in

#### Rate limited

Microsoft Graph API has rate limits. If you see rate limit errors, wait a few moments before trying again.

#### Permission denied

If you see permission errors, you may need to re-authenticate or your admin may have restricted access. Sign out and sign in again:

`bash


Delete token cache to force re-authentication


rm ~/.outlook-mcp/tokens.json
`

#### Notes not available

Outlook Notes are not supported by Microsoft Graph API. If you need access to notes, use the AppleScript backend instead.

How It Works

This MCP server supports two backends:

$3

Uses AppleScript to communicate with Microsoft Outlook for Mac:
- Works best with classic Outlook for Mac
- Requires Outlook to be running
- Works offline (no network required)
- Full support for Notes

$3

Uses Microsoft Graph API to access your data:
- Works with "new Outlook" for Mac (cloud-based)
- Connects directly to Microsoft's servers
- Works without Outlook running
- Supports personal and work/school accounts
- Does not support Notes (Graph API limitation)

Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| USE_GRAPH_API | Set to 1 or true to use Microsoft Graph API backend | (unset, uses AppleScript) |
| OUTLOOK_MCP_CLIENT_ID | Override the embedded Azure AD client ID | (embedded) |
| OUTLOOK_MCP_TENANT_ID | Azure AD tenant ID (common for multi-tenant) | common |

Development

`bash


Install dependencies

npm install

Build

npm run build

Run tests

npm test

Run with coverage

npm run test:coverage

Lint

npm run lint

Type check

npm run typecheck
`

Architecture

`
src/
├── applescript/ # AppleScript integration (default backend)
│ ├── executor.ts # osascript wrapper
│ ├── scripts.ts # AppleScript templates
│ ├── parser.ts # Output parsing
│ ├── repository.ts # IRepository implementation
│ └── content-readers.ts # Content reader implementations
├── graph/ # Microsoft Graph API integration (optional backend)
│ ├── auth/ # Authentication (MSAL, device code flow)
│ │ ├── config.ts # Azure AD configuration
│ │ ├── token-cache.ts # Token persistence
│ │ └── device-code-flow.ts # Authentication flow
│ ├── client/ # Graph client wrapper
│ │ ├── graph-client.ts # API client
│ │ └── cache.ts # Response caching
│ ├── mappers/ # Graph type to row type mappers
│ ├── repository.ts # IRepository implementation
│ └── content-readers.ts # Content reader implementations
├── tools/ # MCP tool implementations
├── types/ # TypeScript type definitions
└── utils/ # Utilities (dates, errors, etc.)
``

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Support Policy: This is a part-time, hobby project. Response times are best-effort (typically 1-2 weeks for bug reports). See SUPPORT.md for details.

$3

- 🐛 Report bugs
- ✨ Suggest features
- 📝 Improve documentation
- 🔀 Submit pull requests
- 💬 Help others in Discussions

$3

This project adheres to our Code of Conduct.

💝 Support This Project

If you find this project valuable, consider supporting its development:

- ⭐ Star this repository
- 💰 Sponsor via GitHub Sponsors
- ☕ Buy Me a Coffee at buymeacoffee.com/jbctechsolutions
- 💵 Donate via PayPal

Your support helps maintain and improve this project! 🙏

📄 License

MIT License

Copyright (c) 2026 JBC Tech Solutions, LLC

See LICENSE file for details.