# 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](https://nodejs.org/) |

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

---

## Install

```powershell
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):

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

### Quick check (Outlook only, no AI)

```powershell
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/`](./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`](./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`](./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`](./examples/opencode.json).

```powershell
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](./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](./SECURITY.md).

---

## License

MIT — see [LICENSE](./LICENSE).