outlook-mcp

Category: Tools & Productivity | Uploader: mpalermiti | Downloads: 0 | Version: v1.0（Latest）

Production-grade MCP server for personal Outlook (Outlook.com / Hotmail / Live). 54 typed Graph tools across mail, calendar, contacts, to-do, drafts, attachments, folders, threading, batch ops. Granular permissions, OS-keyring auth, /$batch-optimized triage. Built for agents that need real Outlook coverage, not a CLI wrapper. BYO Azure app; zero telemetry.

Changelog: Source: GitHub https://github.com/mpalermiti/outlook-mcp

Directory Structure

Current level: tree/main/

📁 .github/
- 📁 workflows/
  - 📄 ci.yml 435 B
📁 src/
- 📁 outlook_mcp/
  - 📁 models/
    
    📄 __init__.py 48 B
    
    📄 calendar.py 2.2 KB
    
    📄 common.py 282 B
    
    📄 contacts.py 1.3 KB
    
    📄 mail.py 2.6 KB
    
    📄 todo.py 2.0 KB
  - 📁 tools/
    
    📄 __init__.py 41 B
    
    📄 admin.py 2.1 KB
    
    📄 auth_tools.py 211 B
    
    📄 batch.py 5.0 KB
    
    📄 calendar_read.py 5.7 KB
    
    📄 calendar_write.py 6.4 KB
    
    📄 contacts.py 7.8 KB
    
    📄 mail_attachments.py 12.2 KB
    
    📄 mail_drafts.py 11.0 KB
    
    📄 mail_folders.py 2.5 KB
    
    📄 mail_read.py 13.5 KB
    
    📄 mail_thread.py 2.3 KB
    
    📄 mail_triage.py 4.7 KB
    
    📄 mail_write.py 5.3 KB
    
    📄 todo.py 13.8 KB
    
    📄 user.py 1.3 KB
  - 📄 __init__.py 252 B
  - 📄 auth.py 9.0 KB
  - 📄 cli.py 2.8 KB
  - 📄 config.py 3.2 KB
  - 📄 errors.py 2.4 KB
  - 📄 folder_resolver.py 5.7 KB
  - 📄 graph.py 987 B
  - 📄 pagination.py 4.0 KB
  - 📄 permissions.py 2.1 KB
  - 📄 server.py 27.5 KB
  - 📄 validation.py 3.7 KB
📁 tests/
- 📄 __init__.py 0 B
- 📄 conftest.py 165 B
- 📄 test_admin.py 3.8 KB
- 📄 test_auth.py 5.3 KB
- 📄 test_batch.py 11.9 KB
- 📄 test_calendar_read.py 6.0 KB
- 📄 test_calendar_write.py 6.5 KB
- 📄 test_config.py 2.7 KB
- 📄 test_contacts.py 14.0 KB
- 📄 test_errors.py 2.9 KB
- 📄 test_folder_resolver.py 8.9 KB
- 📄 test_graph.py 594 B
- 📄 test_integration.py 3.4 KB
- 📄 test_mail_attachments.py 18.0 KB
- 📄 test_mail_drafts.py 17.8 KB
- 📄 test_mail_folders.py 5.1 KB
- 📄 test_mail_read.py 13.4 KB
- 📄 test_mail_thread.py 5.0 KB
- 📄 test_mail_triage.py 9.1 KB
- 📄 test_mail_write.py 5.9 KB
- 📄 test_mail_write_tier2.py 4.3 KB
- 📄 test_models.py 2.8 KB
- 📄 test_models_tier2.py 2.4 KB
- 📄 test_multi_account.py 4.5 KB
- 📄 test_pagination.py 2.3 KB
- 📄 test_pagination_integration.py 7.5 KB
- 📄 test_permissions.py 7.9 KB
- 📄 test_server.py 3.1 KB
- 📄 test_todo.py 18.4 KB
- 📄 test_user.py 3.1 KB
- 📄 test_validation.py 4.9 KB
📄 .gitignore 349 B
📄 CHANGELOG.md 8.2 KB
📄 CLAUDE.md 2.1 KB
📄 LICENSE 1.0 KB
📄 pyproject.toml 1.9 KB
📄 README.md 19.4 KB
📄 ROADMAP.md 3.1 KB
📄 SECURITY.md 1.6 KB
📄 server.json 681 B
📄 SKILL.md 6.1 KB
📄 uv.lock 440.2 KB

SKILL.md

---
name: outlook-mcp
description: Production-grade MCP server for personal Outlook (Outlook.com / Hotmail / Live). 54 typed Graph tools across mail, calendar, contacts, to-do, drafts, attachments, folders, threading, batch ops. Granular permissions, OS-keyring auth, /$batch-optimized triage. Built for agents that need real Outlook coverage, not a CLI wrapper. BYO Azure app; zero telemetry.
homepage: https://github.com/mpalermiti/outlook-mcp
metadata:
  openclaw:
    emoji: "\U0001F4EC"
    requires:
      python: ">=3.10"
    install:
      - id: uv
        kind: shell
        command: "git clone https://github.com/mpalermiti/outlook-mcp.git && cd outlook-mcp && uv sync"
        bins: ["outlook-mcp"]
        label: "Clone and install (uv)"
---

# outlook-mcp

MCP server for Microsoft Outlook personal accounts (Outlook.com, Hotmail, Live).
Provides AI agents with full access to mail, calendar, contacts, and tasks via Microsoft Graph API.

> Independent open-source project. Not affiliated with Microsoft.

## Important

- **Personal Microsoft accounts only** (`@outlook.com`, `@hotmail.com`, `@live.com`). Work/school accounts (Entra ID) are not supported in v1.
- **Requires Azure AD app registration** — free, takes ~5 minutes, but you need a free Azure account first. See README.
- **Auth is CLI-based** — run `outlook-mcp auth` on the host before the agent can use it. No interactive auth through MCP tools.

## Setup

1. **Create a free Azure account** at [azure.microsoft.com/free](https://azure.microsoft.com/free) (sign up with your `@outlook.com` address)
2. **Register an Azure AD app** (see README for step-by-step)
3. **Configure:** Create `~/.outlook-mcp/config.json`:
   ```json
   {
     "client_id": "YOUR-APP-CLIENT-ID",
     "tenant_id": "consumers",
     "timezone": "America/Los_Angeles",
     "read_only": true
   }
   ```
4. **Register with OpenClaw** (writes to `mcp.servers` in `~/.openclaw/openclaw.json`):
   ```bash
   openclaw mcp set outlook '{"command":"uv","args":["--directory","/path/to/outlook-mcp","run","outlook-mcp"]}'
   openclaw mcp list   # verify
   ```
5. **Authenticate on the host:**
   ```bash
   cd /path/to/outlook-mcp && uv run outlook-mcp auth
   ```
6. **Restart the gateway:** `openclaw gateway restart`

## Tools (54)

### Auth
- `outlook_auth_status` — Check authentication status and read-only mode

### Mail — Read
- `outlook_list_inbox` — List messages with filters (folder, unread, sender, date)
- `outlook_read_message` — Get full message by ID
- `outlook_search_mail` — Search mail using KQL query
- `outlook_list_folders` — List all mail folders

### Mail — Write
- `outlook_send_message` — Send email with recipients, CC, BCC, HTML, importance
- `outlook_reply` — Reply or reply-all to a message
- `outlook_forward` — Forward a message

### Mail — Triage
- `outlook_move_message` — Move to a folder
- `outlook_delete_message` — Delete (soft by default, permanent optional)
- `outlook_flag_message` — Set follow-up flag
- `outlook_categorize_message` — Set categories
- `outlook_mark_read` — Mark read or unread
- `outlook_reclassify_message` — Move between Focused Inbox and Other

### Calendar
- `outlook_list_events` — List events in date range (expands recurring)
- `outlook_get_event` — Get event details
- `outlook_create_event` — Create event with attendees, recurrence, online meeting
- `outlook_update_event` — Update event fields
- `outlook_delete_event` — Delete event
- `outlook_rsvp` — Accept, decline, or tentatively accept

### Contacts
- `outlook_list_contacts` — List with cursor pagination
- `outlook_search_contacts` — Search by name or email
- `outlook_get_contact` — Get full details
- `outlook_create_contact` — Create
- `outlook_update_contact` — Update
- `outlook_delete_contact` — Delete

### To Do
- `outlook_list_task_lists` — List To Do lists
- `outlook_list_tasks` — List tasks with status filter and pagination
- `outlook_create_task` — Create with due date, importance, recurrence
- `outlook_update_task` — Update
- `outlook_complete_task` — Mark completed
- `outlook_delete_task` — Delete

### Drafts
- `outlook_list_drafts` — List with pagination
- `outlook_create_draft` — Create for later review
- `outlook_update_draft` — Update
- `outlook_send_draft` — Send
- `outlook_delete_draft` — Delete

### Attachments
- `outlook_list_attachments` — List on a message
- `outlook_download_attachment` — Download and save decoded bytes to a file
- `outlook_send_with_attachments` — Send with files (auto upload session for >3MB)
- `outlook_attach_to_draft` — Add attachments to an existing draft (auto upload session for >3MB)
- `outlook_remove_draft_attachment` — Remove a single attachment from a draft

### Folder Management
- `outlook_create_folder` — Create (top-level or nested)
- `outlook_rename_folder` — Rename
- `outlook_delete_folder` — Delete (refuses well-known folders)

### Threading and Batch
- `outlook_list_thread` — Get all messages in a conversation
- `outlook_copy_message` — Copy to another folder
- `outlook_batch_triage` — Batch move/flag/categorize/mark_read (max 20)

### User and Admin
- `outlook_whoami` — Current user profile
- `outlook_list_calendars` — Available calendars
- `outlook_list_categories` — Category definitions with colors
- `outlook_get_mail_tips` — Pre-send check (OOF, delivery restrictions)
- `outlook_list_accounts` — Configured accounts
- `outlook_switch_account` — Switch active account

## Privacy
- Zero telemetry, zero local caching
- Only connects to `login.microsoftonline.com` and `graph.microsoft.com`
- Tokens stored in OS keyring (macOS Keychain, Windows Credential Store)
- BYOID: you register your own Azure AD app — no shared client ID

## Notes
- IDs are opaque Graph strings — get them from list/search tools, never guess
- Dates are ISO 8601, UTC in responses, config timezone for input interpretation
- Mail search uses KQL syntax
- Start with `read_only: true`, flip when comfortable
- **Granular permissions:** For finer control, set `allow_categories` in config (e.g., `["calendar_write"]` to allow only calendar writes). See README for the 7 categories and example policies.

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

outlook-mcp

Directory Structure

SKILL.md

Report

Notice