axlook-mcp

Let Claude work with New Outlook for Mac: mail, drafts and calendars, without Graph, tokens or app registrations

axlook (Accessibility + Outlook) is a local MCP server that drives the Outlook app you already have open, through the macOS Accessibility API. It sees every account Outlook shows, including Exchange and Microsoft 365 mailboxes whose organization only allows the Outlook app.

/plugin install axlook-mcp --marketplace flol3622/axlook-mcp

🌟 At a Glance

New Outlook for Mac hides cloud accounts from AppleScript: its scripting dictionary sees zero Exchange accounts and an empty Inbox. Microsoft has cancelled its plan to bring AppleScript back. Here is how the usual options compare:

Related MCP server: Apple Mail MCP Server

📦 Install

You need:

• macOS 13 or later

• New Outlook for Mac running, with its language set to English

• Node.js 18+ or Bun (Claude Code users nearly always have one of them)

Claude Code (recommended)

On Claude Code 2.1.275 or later, one command:

/plugin install axlook-mcp --marketplace flol3622/axlook-mcp

On older versions, or to browse the marketplace first:

/plugin marketplace add flol3622/axlook-mcp
/plugin install axlook-mcp@axlook

The plugin bundles:

• the MCP server, a prebuilt universal helper and a single-file server, so there's nothing to compile or npm install;

• a skill that tells Claude to use these tools for every mail and calendar question.

Update with /plugin update axlook-mcp. Third-party marketplaces don't auto-update.

Grant Accessibility (once)

macOS gives the permission to the app that runs Claude, not to axlook itself:

1. Open System Settings → Privacy & Security → Accessibility.

2. Enable the app that runs Claude: Terminal, iTerm, Visual Studio Code, Cursor or Claude.

3. Restart that app.

4. Ask Claude to run outlook_status. It reports trusted: true once permission is in place.

Accessibility lets that app control others. Grant it only to apps you trust, and remove it if you stop using axlook.

Other MCP clients (Claude Desktop, Cursor, VS Code, …)

Clone the repository, then point your client at the bundled launcher:

git clone https://github.com/flol3622/axlook-mcp ~/axlook-mcp

{
  "mcpServers": {
    "axlook": { "command": "/bin/sh", "args": ["/Users/YOU/axlook-mcp/scripts/start.sh"] }
  }
}

If the package is published on npm, npx works too, with no clone needed:

claude mcp add axlook -s user -- npx -y axlook-mcp

🏛️ Architecture

flowchart LR
    subgraph CLIENT["MCP client"]
        A["Claude Code · Claude Desktop · Cursor · …"]
    end

    subgraph SERVER["dist/axlook-mcp.js (Node or Bun)"]
        B["22 MCP tools, one call at a time"]
        C["Outlook UI logic: mail · drafts · calendar"]
        D[".eml parsing, safe attachment saving"]
    end

    subgraph HELPER["dist/axlook-helper (Swift, universal)"]
        E["Generic AX primitives: find · press · set value/date · menus · type · paste · focus"]
    end

    subgraph OUTLOOK["Microsoft Outlook (New Outlook)"]
        F["Main window · reading pane · Save As panel · Move dialog · event peeks and forms"]
        G[("Exchange · Microsoft 365 · Gmail · IMAP: every account Outlook shows")]
    end

    A -- "stdio JSON-RPC" --> B
    B --> C
    C -- "JSON lines" --> E
    C --> D
    E -- "Accessibility API" --> F
    F --- G

    style SERVER fill:#f8f9fa,stroke:#3178c6,stroke-width:2px,color:#000
    style HELPER fill:#f8f9fa,stroke:#f05138,stroke-width:2px,color:#000
    style OUTLOOK fill:#e8f1fb,stroke:#0078d4,stroke-width:2px,color:#000

• The Swift helper is generic. It knows nothing about Outlook, only the Accessibility API. All Outlook-specific knowledge lives in TypeScript (src/outlook/), where it is easy to adjust when Outlook's UI changes.

• No network access of its own. axlook never talks to Exchange, Google or any other service; Outlook does.

🧰 Tools

👻 = runs in the background (Outlook can stay behind your windows, even on another Space). 🪟 = briefly brings Outlook to the front for menus, dialogs or typing, then returns focus.

List and search calls return refs (msg_…, evt_…) that the other tools take as input. Outlook's UI exposes no stable IDs, so a ref encodes where the item is shown and what it looks like. If a ref goes stale, list again.

🚀 Quickstart

Once installed, just ask:

"What's unread in my work inbox? Summarize anything about the conference."

"Save the PDFs from the latest mail from Alice to ~/Downloads/Reviews."

"Move this week's registration notifications into the Conference/Registrations folder."

"Draft a reply to Bob confirming Thursday. Don't send it."

"Block Friday 10:00–11:30 in my Personal calendar for 'Paper revision'."

Tip: tell Claude your own conventions in your CLAUDE.md or a personal skill, for example "work events go in the Calendar of my work account, social ones in 'Family'".

🛡️ Safety by Design

• Nothing is ever sent. Drafts, replies and forwards land in Drafts for you to review. Meetings that would notify attendees are refused.

• Nothing is permanently deleted. Delete moves to Deleted Items, and deleting from a deleted-items folder is refused.

• Your typing wins. If you're writing a draft in Outlook, tools refuse to navigate away from it.

• Keystrokes can't go astray. Keys are delivered only to Outlook's process, and only while it is frontmost. Shortcuts use menu commands rather than key codes, so any keyboard layout works (AZERTY included).

• Your clipboard is restored. Pasted bodies borrow it briefly, mark the paste transient for clipboard managers, and put your clipboard back afterwards.

• Threads are handled one message at a time. Tools never act on a whole conversation row. They expand it and act on the specific message.

• Data stays local. Nothing leaves your Mac except through Outlook itself.

🔬 How It Works

1. Reading across Spaces. AXWindows returns nothing when Outlook is on another Space or in full screen, but AXMainWindow still reaches it. Reading never needs Outlook in front.

2. Full source through Save As. Outlook is sandboxed, so axlook saves the message as .eml into ~/Downloads under a unique name, waits for the write to finish, moves the file into a private temp folder and parses it. That gives Message-ID, HTML and attachments without clicking through the UI.

3. Calendar through event peeks. Each event tile has a hidden "Show event" action. It opens a preview in the background with stable fields for subject, date, time, location, recurrence, organizer and body, plus Edit and Delete buttons.

4. Typing reaches Outlook's data. Writing a field's value only changes what's displayed. Subjects and descriptions are typed as keystrokes into Outlook, then read back to confirm.

⚠️ Limitations

• English UI only. Labels such as "Message List" and the menu titles are matched; localization is future work.

• Speed. Calls take 2–15 seconds, since this is UI automation. Search waits for Outlook's server-side results.

• Read-only meetings. Meetings with attendees can't be created or edited, because that would send mail.

• Recurring events. Edits and deletes apply to the selected occurrence.

• Shared screen. 🪟 tools take Outlook's window for a few seconds. If you switch apps mid-action, axlook re-activates Outlook once, then fails cleanly.

• Locked screen. Nothing works while the Mac is locked.

📊 Verification

The Accessibility selectors were mapped on Outlook 16.114 / macOS 27, against a profile with Exchange, two shared mailboxes and Gmail. scripts/e2e.ts drives every tool through the MCP protocol against the live app.

bun test   # offline: row parser, calendar dates, MIME and attachments
E2E_FOLDER=… E2E_MOVE_TO=… E2E_SELF=… E2E_ATTACH_SCOPE=… E2E_CALENDAR=… bun scripts/e2e.ts

The e2e variables are documented in the header of scripts/e2e.ts.

🛠️ Development

.claude-plugin/        plugin.json (incl. the MCP server entry) + marketplace.json (the repo is its own marketplace)
skills/outlook/        skill shipped with the plugin
scripts/start.sh       launcher: picks Node/Bun, checks the helper (rebuilds it from source if needed)
dist/                  shipped build: axlook-mcp.js (bundle) + axlook-helper (universal, ad-hoc signed)
helper/OutlookAX.swift Accessibility bridge (JSON lines over stdio)
src/                   MCP server (TypeScript): ax.ts, outlook/{session,mail,compose,calendar}.ts, mime.ts
test/                  bun test suites

bun install
bun run build        # dist/axlook-helper (arm64 + x86_64) and dist/axlook-mcp.js
bun test && bun run typecheck
claude plugin validate . --strict

dist/ is committed because the plugin runs it as is. Rebuild and commit it together with any change to src/ or helper/. To release, bump version in both package.json and .claude-plugin/plugin.json.

To inspect Outlook's UI when it changes, use outlook_ui_snapshot, or query the helper directly:

printf '%s\n' '{"id":1,"cmd":"tree","h":"main","depth":3}' | dist/axlook-helper

📖 Acknowledgements

• trsdn/outlook-ax (MIT): its map of New Outlook's accessibility paths was a valuable starting point.

• postal-mime for MIME parsing, and the official MCP TypeScript SDK.

• Built with Claude Code.