[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_108":109},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":-5,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":56,"_57":-5,"_58":50,"_59":44,"_60":61,"_62":-5,"_63":-5,"_64":-5,"_65":-5,"_66":67,"_68":69,"_70":71,"_72":73,"_74":75,"_76":-5,"_77":-5,"_78":-5,"_79":80,"_81":-5,"_82":44,"_83":84,"_85":86,"_87":88,"_89":90,"_91":92,"_93":94},"apiUrl","https://odel.app/api","creator","valter-araujo","moduleId","outlook-mac-mcp","@valter-araujo/outlook-mac-mcp","displayName","Outlook Mac","tagline","MCP server for Outlook personal accounts (Hotmail/Outlook.com) via Microsoft Graph API","iconKey","https://avatars.githubusercontent.com/u/216452496?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","priceCredits",0,"creatorUserId","system:external-import","createdAt",1789718714000,"updatedAt",1790466398000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.valter-araujo%2Foutlook-mac-mcp","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars","upstreamUpdatedAt",1789680910000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/valter-araujo/outlook-mac-mcp","githubRepoFullName","valter-araujo/outlook-mac-mcp","releaseId","ext-valter-araujo-outlook-mac-mcp","version","0.9.0","descriptionMarkdown","# outlook-mac-mcp\n\n\n\nMCP server for Microsoft Outlook, built for **personal Microsoft accounts**\n(Hotmail, Outlook.com, Live) that run on the consumer infrastructure rather than\nExchange Online — and are therefore not supported by the official\n\"Claude for Outlook\" add-in nor by the Microsoft 365 connector.\n\nBackend: **Microsoft Graph API** with delegated, user-consented, least-privilege scopes.\nPython, transport `stdio`, no telemetry.\n\n## Why not AppleScript\n\nCommunity MCP servers for Outlook on Mac drive the app through AppleScript. That\npath only works with **Legacy Outlook**. In August 2026 Microsoft cancelled the\nplanned AppleScript support in New Outlook, and the transition to New Outlook\nends in October 2026. This project deliberately does not depend on it.\n\nThe reference environment for this project runs **New Outlook** (the\n\"Legacy Outlook\" toggle is present in the Outlook menu), where AppleScript\nautomation is unavailable. This was the deciding factor.\n\n## Technical requirements\n\n### Runtime\n\n| Component | Requirement | Notes |\n|---|---|---|\n| macOS | 13 Ventura or later | Keychain used for token storage |\n| Python | 3.12+ | Managed with `uv`; dependencies pinned in `uv.lock` |\n| MCP client | Any stdio client (Claude Desktop, Claude Code) | Tested against Claude Desktop |\n| Network | HTTPS to `login.microsoftonline.com` and `graph.microsoft.com` only | No other outbound calls |\n\n### Microsoft account and app registration\n\n| Item | Requirement |\n|---|---|\n| Account type | Personal Microsoft account (Hotmail / Outlook.com / Live) or work/school |\n| App registration | One-time registration in Microsoft Entra ID (free; a personal account needs its own tenant, created via the Azure Portal) |\n| Supported account types | **\"Accounts in any organizational directory and personal Microsoft accounts\"** |\n| Authentication | Device-code flow (MSAL, public client, **no client secret**) |\n| Authority | `https://login.microsoftonline.com/consumers` |\n| Scopes requested by default | `Mail.Read`, `Calendars.Read`, `Contacts.Read`, `offline_access`, `User.Read` |\n| Scope added by `OUTLOOK_MCP_ENABLE_CALENDAR_WRITE=true` | `Calendars.ReadWrite` (see [Optional: calendar write](#optional-calendar-write)) |\n| Admin consent | Not required — every scope above is user-consentable |\n\n`offline_access`, `openid` and `profile` are reserved scopes: MSAL appends them\nto every request on its own and raises if they are passed explicitly. They are\nconsented at the registration but never appear in the list the code asks for —\nthat consent is what yields the refresh token behind the Keychain cache.\n\nThe app registration may list broader permissions than the server requests. The\ntoken only ever carries the scopes the running configuration asks for: the write\nscope is requested only behind a config flag that is off by default, and turning it\non triggers a new sign-in and consent prompt.\n\n### Not required\n\n- Microsoft Outlook desktop app (the server talks to Graph, not to the app)\n- Exchange Online / Microsoft 365 business tenant\n- Accessibility or Automation permissions on macOS\n- Node.js, Bun, or any non-Python runtime\n\n## Validated environments\n\nOrdered chronologically by validation date (oldest first).\n\n| Version | OS | Python | MCP client | Account type | Outlook app installed | Status |\n|---|---|---|---|---|---|---|\n| 0.1.0 | macOS 27.0 (Golden Gate), Apple M5 | 3.14.7 | Claude Desktop | Personal (`@hotmail.com`) | Outlook for Mac 16.112.4 (26090911), New Outlook, M365 Subscription — not used by the server | **validated** 2026-09-14 |\n| 0.2.0 (calendar write on) | macOS 27.0 (Golden Gate), Apple M5 | 3.14.7 | Claude Desktop | Personal (`@hotmail.com`) | as above | **validated** 2026-09-15 |\n| 0.9.0 (through delete_event) | macOS 27.0 (Golden Gate), Apple M5 | 3.14.7 | Claude Desktop | Personal (`@hotmail.com`) | as above | **validated** 2026-09-17 |\n\nA row moves to **validated** only after the tools it names return correct results on\nthat environment, against a real mailbox. Contributions of new rows are welcome — please\ninclude exact versions.\n\n### Validated tools\n\nSorted alphabetically by tool name. One shipped tool is not in this table yet — it has\nunit and respx coverage but no live validation against a real mailbox:\n\n- `search_contacts` — no contact exists in the test mailbox to search for yet.\n\n| Tool | Validated | What was checked |\n|---|---|---|\n| `count_emails` | 2026-09-15 | A received-time range covering one month returned an exact count. |\n| `create_event` | 2026-09-15, 2026-09-16, 2026-09-17 | Created a timed event and an all-day event; Graph accepted the all-day payload with the resolved zone's name, and both came back readable. A body from the preview was written to the created event correctly. An event with no body at all also succeeded, confirming the fix for Graph defaulting an unsent body to HTML. |\n| `delete_event` | 2026-09-17 | Deleted the event previewed under `preview_event_deletion`'s token; confirmed removed from the calendar directly in Outlook. |\n| `get_email` | 2026-09-14 | Text body returned with the `Prefer` header honoured; the malformed id `nope` came back as `ErrorInvalidIdMalformed` and was mapped to `InvalidRequestError`. |\n| `list_emails` | 2026-09-15 | `sort=oldest`, `limit=1` returned the folder's earliest email with an exact total; an exact-sender filter with `sort=newest` returned exactly one match, and Graph accepted the sender filter combined with `$orderby` without an `InefficientFilter` error. |\n| `list_folders` | 2026-09-17 | Discovered 100+ custom folders correctly, including several levels of nesting, each with accurate per-folder unread/total counts. Confirmed the documented limitation live: a Microsoft-managed folder with no well-known flag (Deleted Items) appeared in `custom` as expected, alongside genuine user-created folders. |\n| `list_largest_emails` | 2026-09-16 | Returned ranked results with real sizes from the extended property, `skipped` near zero. |\n| `list_todays_events` | 2026-09-15 | Returned zero events, exact, on a free day. |\n| `list_unread_emails` | 2026-09-14 | Reads a Hotmail inbox through Graph. |\n| `list_upcoming_events` | 2026-09-15 | Returned the matching events, earliest first; confirmed both an all-day event and a timed event mapped correctly in the resolved time zone. |\n| `preview_event` | 2026-09-15, 2026-09-16 | Summary and token for a timed and an all-day event; a body well under the truncation threshold showed in full, verbatim, in the preview. |\n| `preview_event_deletion` | 2026-09-17 | Showed the complete event (every field, unabbreviated) with the irreversibility warning before any deletion happened. |\n| `preview_event_update` | 2026-09-17 | A time change (10:00–10:30 -> 11:00–11:30) produced a diff summary showing only the changed field, old value -> new value. |\n| `search_emails` | 2026-09-14, 2026-09-15, 2026-09-17 | A term matching several emails returned an exact total; `scope=subject` and `scope=sender` each returned a narrower, still-exact subset; a term trying to break out of the phrase returned empty with no 400. Passing `next_page_token` back as `page_token` returned a genuinely different second page (a different date window, no items repeated from the first), with `total`/`total_is_exact` still accurate on that page. |\n| `top_senders` | 2026-09-15 | A full inbox scan hit the configured ceiling with `coverage_is_complete=false`; the client reported the partial coverage explicitly, as the description asks. |\n| `update_event` | 2026-09-17 | Applied the previewed time change (10:00–10:30 -> 11:00–11:30) exactly; the updated event reflected only that change. |\n\nEvery tool below has been validated against a real mailbox on the environment above;\n`search_contacts` has unit and respx coverage but no live validation yet (see above).\nSearch quoting is additionally covered by a live positive-control check, see\n[Integration tests](#integration-tests).\n\n## Scope\n\n- **v1 (read-only):** unread emails, emails by folder (well-known or custom, by\n full path), search by term, read one email by id (body included), list\n folders, today's / upcoming events, contact search.\n- **v2:** create and update calendar events — behind a config flag, off by\n default; delete calendar events — behind a second flag, off by default even\n when the first one is on; mark as read — not yet built.\n- **v3:** send email — behind a config flag, off by default, with explicit\n per-call confirmation.\n\n## Tools\n\nRead tools are always registered. The four tools marked `v2, flagged` register only\nwhen `OUTLOOK_MCP_ENABLE_CALENDAR_WRITE=true` (see\n[Optional: calendar write](#optional-calendar-write)). `preview_event_deletion` and\n`delete_event`, marked `v2, flagged + calendar delete`, additionally need\n`OUTLOOK_MCP_ENABLE_CALENDAR_DELETE=true` (see\n[Optional: calendar delete](#optional-calendar-delete)). Sorted alphabetically by tool name.\n\n| Tool | What it does |\n|---|---|\n| `count_emails` | Count emails matching the same filters as `list_emails`, exactly, without listing them. |\n| `create_event` (v2, flagged) | Create the event previewed under a token from `preview_event`. |\n| `delete_event` (v2, flagged + calendar delete) | Delete the event previewed under a token from `preview_event_deletion`. Irreversible. |\n| `get_email` | Fetch one email by id, body included. |\n| `list_emails` | List emails in a folder with any combination of filters (read state, sender, date range, attachments), sorted newest or oldest, with an exact total. |\n| `list_folders` | List the mailbox's well-known folders with their unread and total item counts, plus every user-created folder found by walking the mailbox tree, each identified by its full path. |\n| `list_largest_emails` | List a folder's largest emails by byte size, largest first, scanning up to 10,000 matching emails per call; emails with no determinable size are counted separately in `skipped`. |\n| `list_todays_events` | List today's calendar events, earliest first. |\n| `list_unread_emails` | List unread emails in a folder, newest first. |\n| `list_upcoming_events` | List calendar events from now through 1–30 days ahead. |\n| `preview_event` (v2, flagged) | Validate a new event and return a token and a summary, without creating it. |\n| `preview_event_deletion` (v2, flagged + calendar delete) | Fetch an existing event and return a token and a summary showing every field, unabbreviated, without deleting anything. |\n| `preview_event_update` (v2, flagged) | Fetch an existing event, validate the requested changes, and return a token and a diff summary (old value -> new value, changed fields only), without applying anything. |\n| `search_contacts` | Search contacts by a display-name prefix or an exact email address. |\n| `search_emails` | Search a folder for a term, ranked by relevance, not by date. |\n| `top_senders` | Rank a folder's senders by how many emails each sent, scanning up to 10,000 matching emails per call. |\n| `update_event` (v2, flagged) | Apply the change previewed under a token from `preview_event_update`. Only the fields actually passed to the preview are changed. |\n\n### Custom folders\n\nA custom folder is any folder the user created in Outlook — not one of the five\nwell-known folders (inbox, archive, junk email, sent items, drafts). `search_emails`,\n`list_emails`, `count_emails`, `top_senders`, `list_largest_emails` and\n`list_unread_emails` all accept one of the following as their `folder` argument:\n\n1. **A well-known folder by name, matched case-insensitively** — `folder=\"inbox\"`,\n `folder=\"INBOX\"` and `folder=\"Archive\"` all resolve the same way.\n2. **`all`** — every well-known folder, merged. Custom folders are never included,\n however many exist: `folder=\"all\"`.\n3. **A custom folder by its full path**, exactly as `list_folders` reports it under\n `custom` (folder names repeat across a mailbox; the full path is what disambiguates\n them): `folder=\"Entrevistas/Work/AWS\"`.\n4. **A top-level custom folder**, which has no parent to qualify it:\n `folder=\"Seguros\"`.\n\nRun `list_folders` first to discover the exact paths available, then pass that string\nas `folder`. Resolving a custom path costs one extra walk of the mailbox's folder tree\nper call (the same walk `list_folders` does for its `custom` list) — nothing is cached\nbetween calls.\n\n`folder` combines with every other filter a tool already accepts:\n\n```\n# Well-known folder (unchanged)\nsearch_emails(term=\"Cargill\", folder=\"archive\")\n\n# All well-known folders (unchanged — never includes custom folders)\ncount_emails(folder=\"all\")\n\n# A custom folder, addressed by its full path\nlist_emails(folder=\"Entrevistas/Work/AWS\", sort=\"oldest\")\n\n# A top-level custom folder\ntop_senders(folder=\"Seguros\")\n\n# A custom folder combined with a date range\nlist_emails(\n folder=\"Entrevistas/Work/AWS\",\n received_after=\"2026-01-01T00:00:00+00:00\",\n sort=\"oldest\",\n)\n\n# A custom folder combined with an exact sender filter\ncount_emails(folder=\"Entrevistas/Work/AWS\", sender=\"ana@example.com\")\n\n# A custom folder combined with a search term\nsearch_emails(term=\"offer letter\", folder=\"Entrevistas/Work/AWS\")\n```\n\n**Typos are rejected, not silently misrouted.** A `folder` value close to a well-known\nname — one or two characters off, e.g. `folder=\"inbx\"` — raises an error naming the\nvalue it was likely meant to be (`\"inbx\" is not a recognized folder -- did you mean\n'inbox'?`) instead of walking the whole mailbox tree looking for a custom folder\nliterally called `inbx`.\n\n**Known limitation:** this typo check is a coarse edit-distance heuristic, not a\ndictionary lookup. A genuine custom folder whose name happens to be one edit away from\na well-known one — for example a folder literally named `Archives` — is\nindistinguishable from a typo of `archive` and gets rejected the same way. Renaming the\nfolder is the only workaround today.\n\n## Security model\n\n- Least privilege: the token can only do what the requested scopes allow, even\n if the server process is compromised.\n- Tokens are stored in the macOS Keychain, never in files or environment\n variables.\n- Email content is treated as untrusted input. The server never acts on\n instructions found inside message bodies.\n- Structured JSON logs go to `stderr` (stdout is the MCP transport). Logs\n contain metadata and counts only — never subjects, bodies, addresses, or\n contact names.\n\n## Architecture\n\n```\ndomain/ entities and rules — no Graph, no MCP\napplication/ use cases depending on ports (interfaces)\ninfrastructure/ Graph API adapter — the only place that knows Microsoft\ninterface/mcp/ tool registration and input/output translation only\n```\n\nDependencies point inward. Swapping the backend touches `infrastructure/` only.\n\n## Architecture at a glance\n\nDependencies point inward. The Graph adapters implement most ports; the one exception\nis `Clock`, implemented by `SystemClock`, which lives outside `infrastructure/graph`\nsince it never talks to Microsoft. Nothing in `domain/` or `application/` imports either.\n\n```mermaid\nflowchart TB\n subgraph interface[\"interface/mcp — translation only\"]\n tools[\"MCP tools
pydantic input · flat output views\"]\n end\n subgraph application[\"application — use cases\"]\n uc[\"ListUnreadEmails · SearchEmails · GetEmail
ListEmails · CountEmails · TopSenders · ListLargestEmails
ListTodaysEvents · ListUpcomingEvents
PreviewEvent · CreateEvent
PreviewEventUpdate · UpdateEvent
PreviewEventDeletion · DeleteEvent
ListFolders · SearchContacts\"]\n ports[\"Ports (Protocol)
MailRepository · CalendarRepository · CalendarWriter
ContactRepository · MailFolderRepository · Clock\"]\n end\n subgraph domain[\"domain — entities and rules\"]\n ent[\"Email · Event · Contact · Page · TimeWindow
frozen dataclasses · no Graph, no MCP\"]\n end\n subgraph infra[\"infrastructure/graph — the only place that knows Microsoft\"]\n adapters[\"Graph adapters
query builders · JSON→entity mappers\"]\n auth[\"MSAL device-code
token cache in macOS Keychain\"]\n http[\"httpx client
host-pinned to graph.microsoft.com\"]\n end\n clock[\"infrastructure/system_clock
SystemClock — reads the resolved time zone\"]\n tools --> uc\n uc --> ports\n uc --> ent\n adapters -. implements .-> ports\n clock -. implements .-> ports\n adapters --> http\n http --> auth\n```\n\nOne read call end to end. Input is validated before it becomes a query; logs carry\nmetadata and counts, never content.\n\n```mermaid\nsequenceDiagram\n participant CD as Claude Desktop\n participant S as MCP server (stdio)\n participant UC as Use case\n participant A as Graph adapter\n participant K as macOS Keychain\n participant G as Microsoft Graph\n CD->>S: tools/call list_unread_emails {folder, limit}\n S->>S: validate input (pydantic) → request object\n S->>UC: execute(request)\n UC->>A: list_unread(folder, limit)\n A->>K: read cached token (MSAL silent refresh)\n K-->>A: access token\n A->>G: GET /me/mailFolders/inbox/messages?$filter…&$orderby…&$top…&$count=true\n G-->>A: JSON page + @odata.count\n A-->>UC: Page[Email]\n UC-->>S: Page[Email]\n S-->>CD: {items, returned, total, total_is_exact}\n Note over S: JSON log to stderr: correlation id, tool, duration, count — never content\n```\n\n## Development\n\n```\nuv sync\nuv run ruff check .\nuv run ruff format --check .\nuv run mypy\nuv run pytest\n```\n\n### Integration tests\n\nTests marked `@pytest.mark.integration` reach the real Microsoft Graph API and are\ndeselected by default. They need a completed sign-in (see\n[Installation](#3-sign-in-once)) and the client id in the environment:\n\n```\nexport OUTLOOK_MCP_CLIENT_ID=\nuv run pytest -m integration\n```\n\nThey read the signed-in mailbox but never write to it, and they provision their own\nfixtures: no particular message has to exist, and a test skips rather than fails if the\nmailbox yields nothing to work with.\n\nOne of them is load-bearing rather than incidental. `test_search_query_live.py` checks\nthat Graph parses a search term as literal text instead of as a query, by sending the\nsame string in the safe form and in the form this project used to send, and comparing\nresult counts against a sender taken from the mailbox itself. A unit test cannot show\nthis: it can only assert the bytes we send, and every unit test passed while terms were\nin fact being executed as queries. Run it after touching anything about how a query is\nquoted, escaped or encoded.\n\n## Installation\n\n### 1. Register the app in Microsoft Entra ID\n\nFollow the table under [Microsoft account and app registration](#microsoft-account-and-app-registration).\nNote the **Application (client) ID** — it is not a secret, but it identifies your\nregistration and does not belong in this repository.\n\n### 2. Install\n\n```sh\ngit clone https://github.com/valter-araujo/outlook-mac-mcp.git\ncd outlook-mac-mcp\nuv sync\n```\n\n### 3. Sign in once\n\nThe MCP server never starts a sign-in of its own: the device-code flow blocks for\nminutes waiting for a browser, and a stdio server has nowhere to show the code,\nbecause stdout carries the MCP protocol. Authenticate out of band instead:\n\n```sh\nexport OUTLOOK_MCP_CLIENT_ID=\nuv run outlook-mac-mcp sign-in\n```\n\nThe code and the URL are printed to stderr. Open the URL, enter the code, and approve\nthe requested scopes. The resulting token is stored in the macOS Keychain under the\nservice `outlook-mac-mcp`; it is never written to a file or an environment variable.\n\nRepeat this only when the refresh token expires or you revoke consent.\n\n### 4. Point Claude Desktop at the server\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"outlook-mac-mcp\": {\n \"command\": \"uv\",\n \"args\": [\"--directory\", \"/absolute/path/to/outlook-mac-mcp\", \"run\", \"outlook-mac-mcp\"],\n \"env\": {\n \"OUTLOOK_MCP_CLIENT_ID\": \"\"\n }\n }\n }\n}\n```\n\nThree things this configuration has to get right:\n\n- **`OUTLOOK_MCP_CLIENT_ID` must be in the `env` block.** Claude Desktop launches the\n server as a GUI process, which does not inherit your shell environment: an `export` in\n `~/.zshrc` is invisible to it. The `env` block is the only thing the server sees.\n- **Use an absolute path** in `--directory`. The launched process does not start in your\n project directory.\n- **`uv` must be on the launcher's `PATH`,** which is likewise not your shell's. If the\n server fails to start, replace `\"command\": \"uv\"` with the absolute path from\n `which uv` (typically `~/.local/bin/uv`).\n\nRestart Claude Desktop. `list_unread_emails` and the other read tools should appear in\nthe tool list; the four create/update tools appear only with the write flag on, and\n`preview_event_deletion`/`delete_event` need the delete flag on top of that (see\n[Optional: calendar delete](#optional-calendar-delete)).\n\n### Optional: log level\n\n`OUTLOOK_MCP_LOG_LEVEL` sets the verbosity (default `INFO`). Structured JSON logs go to\nstderr and carry metadata only — tool name, correlation id, duration, outcome and item\ncount, never subjects, addresses or bodies. Add it to the same `env` block.\n\n### Optional: time zone\n\nCalendar tools express every time in one zone and decide what \"today\" means from it.\nBy default that is the machine's time zone, as reported by the operating system. To\noverride it, add `OUTLOOK_MCP_TIMEZONE` with an IANA name (for example\n`America/Sao_Paulo` or `Europe/Lisbon`) to the same `env` block. The name is validated\nat startup: an unknown one stops both the server and `sign-in` with a\n`ConfigurationError`. The resolved zone is logged at startup.\n\n### Optional: calendar write\n\nOff by default. Setting `OUTLOOK_MCP_ENABLE_CALENDAR_WRITE=true` in the `env` block\ndoes two things: the server requests the `Calendars.ReadWrite` scope in addition to the\nread scopes, and it registers the create and update tools. Accepted values are `true`,\n`false`, `1` and `0`; anything else stops the server with a `ConfigurationError`.\n\nBecause the scope set changes, the token already in the Keychain no longer satisfies\nit and every tool fails with \"no usable cached credential\" until you sign in again.\nRun the sign-in with the flag set in the same shell, and approve the new consent\nprompt, which now lists calendar write access:\n\n```sh\nexport OUTLOOK_MCP_CLIENT_ID=\nexport OUTLOOK_MCP_ENABLE_CALENDAR_WRITE=true\nuv run outlook-mac-mcp sign-in\n```\n\nTurning the flag off again does not shrink the consent already granted; revoke it at\n if you want the write permission gone.\n\nWith the flag on, four tools appear, as two independent preview-then-confirm pairs:\ncreate and update. A third pair, delete, needs its own additional flag on top of this\none — see [Optional: calendar delete](#optional-calendar-delete) — precisely because it\nis the one pair whose apply step cannot be undone. Each pair is always a two-step\nhandshake, and each has its own token namespace — a token from one pair is refused by\nevery other pair's apply tool, not just reused within its own.\n\n1. `preview_event` takes the full details of a new event — subject; start and end with\n UTC offsets; an all-day flag; an optional free-text location; an optional plain-text\n body, up to 32,768 characters; up to 50 attendee addresses; an optional reminder lead\n time in minutes; an optional sensitivity (`normal`, `personal`, `private` or\n `confidential`); and an optional free/busy status to show as (`free`, `tentative`,\n `busy`, `oof` or `workingElsewhere`) — validates them, and returns a one-line summary\n plus an opaque token. Nothing is written. `create_event` takes only that token and\n performs the real change.\n2. `preview_event_update` takes an event id and any subset of the same fields **except**\n the all-day flag, which is never changeable after creation and always carries over\n from the current event: subject, start, end, location, body, attendees, reminder lead\n time, sensitivity and show-as. It fetches the current event, and returns a token plus\n a summary showing the diff for each changed field as old value -> new value — never\n just the resulting state. A field left out of the call is left exactly as it is.\n `update_event` takes only that token and applies just the changed fields.\n\nEvery apply tool's token works exactly once and only within the same server process;\nan unknown token, an already used token, or a token issued by a different pair's\npreview tool is refused, and a server restart discards every pending draft. This rule\nholds across every pair, including delete, described next.\n\nEvery tool description instructs the client to show the summary and get the user's\nagreement before applying, and to get explicit confirmation of every detail before even\npreviewing when any of it came from email content. Email is untrusted input; a message\ncan be written to talk a model into changing your calendar, and the user, never the\nemail, decides.\n\n### Optional: calendar delete\n\nOff by default, and independent of calendar write — setting\n`OUTLOOK_MCP_ENABLE_CALENDAR_DELETE=true` by itself does nothing.\n`preview_event_deletion` and `delete_event` register only when **both** flags are\n`true`: calendar write builds the Graph calendar writer these two tools call through,\nand this flag then adds the one irreversible action on top of it. No additional Graph\nscope is requested — `Calendars.ReadWrite`, already required by calendar write, covers\ndelete on the Graph side too, so no extra consent prompt is needed beyond the one from\n[Optional: calendar write](#optional-calendar-write).\n\n```sh\nexport OUTLOOK_MCP_CLIENT_ID=\nexport OUTLOOK_MCP_ENABLE_CALENDAR_WRITE=true\nexport OUTLOOK_MCP_ENABLE_CALENDAR_DELETE=true\nuv run outlook-mac-mcp sign-in\n```\n\n`preview_event_deletion` takes an event id, fetches the current event, and returns a\ntoken plus a summary showing every field of the event, unabbreviated — subject, start,\nend, location, body and attendees — so the confirmation shows exactly what would be\nremoved. This matters most when two similar events exist and only their full detail\ntells them apart. `delete_event` takes only that token and deletes the event; this\ncannot be undone by the server. The pair follows the same token rules as create and\nupdate — single use, its own namespace, refused by every other pair's apply tool.\n\n### Troubleshooting\n\n| Symptom | Cause |\n|---|---|\n| Tool fails with \"no usable cached credential\" | Step 3 was not completed, or the token was revoked. Run `sign-in` again. |\n| Server fails to start with `ConfigurationError` | `OUTLOOK_MCP_CLIENT_ID` is missing from the `env` block, or `OUTLOOK_MCP_TIMEZONE` is not an IANA time zone name. |\n| Server does not appear in Claude Desktop | `uv` is not on the launcher's `PATH`; use an absolute path for `command`. |\n\n## Disclaimer\n\nThis project is provided \"as is\", without warranty of any kind (see\n[LICENSE](https://github.com/valter-araujo/outlook-mac-mcp/blob/main/LICENSE)). The author is not responsible for how others configure,\nrun, or deploy this code, nor for data loss or any other consequence of doing\nso.\n\nThe calendar-write tools perform real changes through Microsoft Graph, and\n`delete_event` cannot be undone by this server. Test against a low-stakes or\ndisposable event first — see [Optional: calendar\nwrite](#optional-calendar-write) — before relying on it for anything that\nmatters.\n\n## License\n\nMIT\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt",1789680975000,"priceCents","trialDays","iconType","image","upstream",{"_97":98,"_99":100,"_101":102,"_103":104,"_105":-5,"_106":107},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_95":44,"_96":44},"ratingAvg","reviewCount","topics",[],"license","MIT","language","Python","registryName","io.github.valter-araujo/outlook-mac-mcp","homepage","packages",[],"ENV",{"_110":111,"_112":113,"_114":115,"_116":-7},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272","SENTRY_ENABLE_LOCAL"]