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:

1. list_mailboxes — see accounts
2. inbox_summary — quick overview
3. get_mail / search_mail — details
4. 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

1. Build the project (npm run build).
2. Copy an example from examples/.
3. Replace C:\\ABS\\PATH\\TO\\outlook-mcp with your real folder path.
4. 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

1. Create e.g. powershell/lib/60-myfeature.ps1 and register an action.
2. Add a matching tool in src/mcp/tools.ts.
3. 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.