outlook-mcp

Let Cursor, Claude Desktop, or OpenCode read and send your Outlook mail — locally on Windows.

This is a small MCP server. It talks to the Outlook app already on your PC (COM/MAPI).
It does not use Microsoft Graph, Azure, or cloud APIs.

Windows + Outlook Desktop only. macOS/Linux are not supported.

What you get

After setup, your AI can:

list mailboxes and folders
summarize the inbox (unread + recent)
search, open, reply, forward, and send mail
mark, move, delete messages
save attachments to disk

Typical flow the model should use:

list_mailboxes — see accounts
inbox_summary — quick overview
get_mail / search_mail — details
reply_mail or send_mail — act

Requirements

Need	Notes
Windows	Required
Outlook Desktop	Signed in with your mailbox
Node.js 18+	nodejs.org

Outlook may show a security prompt the first time another app accesses mail — allow it.

Install

git clone https://github.com/YOUR_USER/outlook-mcp.git
cd outlook-mcp
npm install
npm run build

Optional: set a default mailbox (otherwise Outlook’s default account is used):

$env:OUTLOOK_MAILBOX = "you@example.com"

Quick check (Outlook only, no AI)

powershell -NoProfile -STA -ExecutionPolicy Bypass `
  -File .\powershell\Invoke-Outlook.ps1 `
  -Action list_mailboxes

If you see JSON with "ok": true and your accounts, the bridge works.

Connect an AI client

Build the project (npm run build).
Copy an example from examples/.
Replace C:\\ABS\\PATH\\TO\\outlook-mcp with your real folder path.
Restart the client.

Use the full path to node.exe and dist\\server.js (recommended on Windows).

Cursor

Settings → MCP, or project file .cursor/mcp.json — see examples/cursor.mcp.json.

Claude Desktop

Edit claude_desktop_config.json:

Often: %APPDATA%\Claude\claude_desktop_config.json
MSIX/Store installs may instead use:
%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

Template: examples/claude_desktop_config.json.
Fully quit Claude Desktop (tray icon too), then start it again.

OpenCode CLI

Project or global opencode.json — see examples/opencode.json.

opencode mcp list

You want outlook-mcp = connected.

Tools (cheat sheet)

Tool	When to use it
`list_mailboxes`	First call — which accounts exist?
`list_folders`	Where can mail go?
`inbox_summary`	Fast unread + recent overview
`read_folder` / `read_inbox`	List messages with filters
`search_mail`	Find by text / from / to / subject / date
`get_mail`	Full body of one message (`entryId`)
`list_conversation`	Same thread
`send_mail`	New email
`create_draft`	Save without sending
`reply_mail`	Reply (optional `replyAll`, or draft with `send: false`)
`forward_mail`	Forward
`mark_mail`	Read / unread / categories
`move_mail`	Move to a folder
`delete_mail`	Delete
`save_attachments`	Write attachments to a folder
`list_actions`	Debug: which bridge actions are loaded

How it works

AI client  →  outlook-mcp (Node, stdio)  →  PowerShell  →  Outlook COM/MAPI  →  mailbox

Nothing is sent to Azure for mail access. The AI host only starts this local process.

Project layout

src/                  Node MCP server
  mcp/tools.ts        ← add new MCP tools here
powershell/
  Invoke-Outlook.ps1  loader + shared helpers
  lib/*.ps1           ← add new Outlook actions here
examples/             client config templates

Add your own feature

Create e.g. powershell/lib/60-myfeature.ps1 and register an action.
Add a matching tool in src/mcp/tools.ts.
Run npm run build.

Details: CONTRIBUTING.md.

Troubleshooting

Problem	What to try
Bridge JSON error / Outlook COM unavailable	Start Outlook once, sign in, retry
Wrong mailbox	Set `OUTLOOK_MAILBOX` or pass `mailbox` on the tool
Claude MCP not loading	Edit the MSIX config path above; restart completely
`node` not found	Use `C:\Program Files\nodejs\node.exe` in the config
Tools timeout	Increase client timeout (OpenCode example uses `60000`)
Empty inbox results	Confirm the account appears in `list_mailboxes`

Security

Local stdio only — do not publish this as an open network server without auth.
send_mail, delete_mail, and save_attachments have real side effects.
Prefer drafts (create_draft, or send: false on reply/forward) while testing.

More: SECURITY.md.

License

MIT — see LICENSE.