ap311036/ews-meeting-mcp

The MCP server for safely reading Outlook inbox messages, sending self-only reports, and scheduling meetings on on-prem Exchange EWS.
EWS Meeting MCP gives coding assistants and desktop agents a safe, structured way to read Outlook inbox messages and availability, send a report only to the configured mailbox, discover rooms, suggest meeting slots, and create, update, or cancel meetings only after an explicit human confirmation step.
It is built for companies where calendar access is sensitive infrastructure: regulated teams, internal networks, strict security review, legacy Exchange deployments, and organizations that cannot simply hand a cloud agent broad Microsoft 365 permissions. Credentials stay local, meeting writes are previewed before they touch Exchange, self-only report sends require idempotency protection, and every write can be traced through a local audit trail.
Why This Exists
Many teams still run calendar infrastructure through on-prem Exchange/EWS. General-purpose agents can reason about scheduling, but they should not receive raw passwords, guess attendee addresses, or send calendar invitations without a reviewable checkpoint.
This is not a generic Outlook wrapper or a Microsoft Graph-first calendar connector. It is designed for the stricter enterprise case: local EWS access, room resources, explicit human approval, duplicate-send protection, and audit-friendly meeting lifecycle tools.
This project wraps Exchange calendar operations in a small MCP surface with:
- **Room-aware scheduling**: finds overlapping attendee availability and filters meeting rooms by Exchange discovery or local policy.
- **Human-in-the-loop writes**: create, update, and cancel operations require a preview plus a matching confirmation_id.
- **Outlook Show As**: create or update personal appointments with show_as: "out_of_office" (EWS OOF). Empty attendees and rooms never send invitations; this does not configure email automatic replies.
- **Local-first credential handling**: reads .env, shell environment, or macOS Keychain without passing passwords through the model.
- **Structured recovery**: setup failures return machine-readable error codes and user-facing setup commands.
- **Auditability**: lifecycle previews, confirmed actions, duplicate confirmations, in-progress states, and structured errors are written to a local JSONL audit log.
- **Agent-ready instructions**: the MCP server exposes tool descriptions and initialization guidance, and the repo includes a companion skill for agents that support skills.
What Agents Can Do
| Capability | Tooling | Safety posture |
| --- | --- | --- |
| Check setup and credentials | ews_setup_check, ews_keychain_status | Never returns the EWS password |
| Set up meeting signatures | ews_signature_setup_guide | Returns copyable HTML sample and local env guidance |
| Read Outlook inbox | ews_search_emails, ews_read_email | Read-only; does not mark messages as read or change mailbox state |
| Send a weekly report to self | ews_send_email_to_self | Only sends to EWS_EMAIL; recipient is not an input; requires a stable idempotency key and real EWS CreateItem + SendItem |
| Read calendar availability | ews_list_calendar, ews_get_free_busy, ews_find_calendar_events | Read-only |
| Resolve people and rooms | ews_resolve_attendees, ews_list_rooms | Uses Exchange directory when available |
| Suggest slots | ews_suggest_slots | Applies local workday, avoid windows, and room capacity |
| Create meetings | ews_create_meeting_preview, ews_create_meeting_confirmed | Supports optional weekly recurrence; requires preview, explicit approval, and matching confirmation id |
| Update meetings | ews_update_meeting_preview, ews_update_meeting_confirmed | Requires exact EWS item metadata and matching confirmation id |
| Cancel meetings | ews_cancel_meeting_preview, ews_cancel_meeting_confirmed | Requires exact EWS item metadata and matching confirmation id |