# outlook-mcp

MCP server for **Microsoft Outlook desktop** via COM.
MCP server cho **Outlook desktop** qua COM.

Reads the Outlook profile already signed in on your machine — **no OAuth, no tokens,
no tenant admin consent**. Useful where Microsoft Graph application access is blocked
by IT policy.

Đọc thẳng profile Outlook đang đăng nhập trên máy — **không OAuth, không token, không
cần quản trị viên phê duyệt**. Dùng được khi tenant chặn app Microsoft Graph.

**The server never sends mail.** It can create drafts; sending stays a human action.
**Server không bao giờ gửi thư.** Chỉ tạo nháp; việc gửi do người quyết định.

---

## Requirements / Yêu cầu

- Windows
- Outlook desktop installed and signed in / đã cài và đã đăng nhập
- Python ≥ 3.10, [uv](https://docs.astral.sh/uv/)

## Install / Cài đặt

```bash
git clone <repo-url> C:\Tools\outlook-mcp
cd C:\Tools\outlook-mcp
uv sync
```

## Register with Claude / Đăng ký với Claude

Add to `claude_desktop_config.json` / Thêm vào `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "outlook": {
      "command": "C:\\Tools\\outlook-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "outlook_mcp"]
    }
  }
}
```

Restart Claude. / Khởi động lại Claude.

---

## Tools / Công cụ

| Tool | Read-only | Purpose |
|---|---|---|
| `outlook_list_folders` | ✅ | List mail folders with counts. Call first to find a `folder_path`. |
| `outlook_search_mail` | ✅ | Search subject+body by keyword, folder, sender, recency, internal/external scope. Paginated. |
| `outlook_get_message` | ✅ | Full body and attachment listing for one message. |
| `outlook_get_thread` | ✅ | Every message in a conversation, oldest first. |
| `outlook_save_attachments` | — | Write attachments straight to disk. |
| `outlook_export_messages` | — | Bulk-export to a markdown archive with YAML front matter. |
| `outlook_create_draft` | — | Save an unsent draft. **Never sends.** |
| `outlook_move_messages` | — | File messages into another folder. Dry-run by default; never deletes. |

Attachment bytes go from Outlook straight to disk and never pass through the
conversation, so file size is not a constraint.

Nội dung file đính kèm đi thẳng từ Outlook xuống đĩa, không đi qua hội thoại, nên
không bị giới hạn dung lượng.

---

## Design notes / Ghi chú thiết kế

Three things that are easy to get wrong with the Outlook object model:

**`MailItem.To` gives display names, not addresses.** Resolving a real SMTP address
needs `Recipients` → `AddressEntry` → `PR_SMTP_ADDRESS` (`0x39FE001E`). Skip this and
any internal/external classification is wrong for every message.

`MailItem.To` chỉ trả **tên hiển thị**, không có địa chỉ. Phải đi qua `Recipients` →
`AddressEntry` → `PR_SMTP_ADDRESS`, nếu không phân loại nội bộ/đối ngoại sai hết.

**Most attachments are flagged `inline`, including real documents.** Filtering on that
flag alone throws away screenshots pasted into a mail, which are often the actual
evidence being discussed. This server filters by **size** instead (`min_inline_kb`,
default 100 KB) so logos and signatures drop out but content images stay.

Phần lớn đính kèm bị gắn nhãn `inline`, kể cả tài liệu thật. Lọc theo nhãn đó sẽ mất
ảnh chụp màn hình dán trong thư — thường chính là bằng chứng đang bàn. Server lọc theo
**kích thước** (`min_inline_kb`, mặc định 100 KB).

**Paths overflow `MAX_PATH` (260).** Long subject lines produce long folder names;
`Attachment.SaveAsFile` then fails with a misleading "Path does not exist". File names
are shortened, keeping the extension plus a short hash so truncated names never collide.

Chủ đề thư dài làm đường dẫn vượt `MAX_PATH` 260 ký tự và `SaveAsFile` báo lỗi khó hiểu.
Server tự rút gọn tên file, giữ đuôi và thêm hash ngắn để không trùng.

Outlook's object model is apartment-threaded, so all COM work is funnelled through a
single dedicated worker thread owning one apartment.

---

## Privacy / Riêng tư

This server reads your mailbox. Anything exported lands on your local disk.
**Do not commit exported mail, attachments, or logs to a public repository** — check
`.gitignore` before pushing.

Server đọc hộp thư của bạn; dữ liệu xuất ra nằm trên đĩa cục bộ.
**Đừng commit thư, đính kèm hay log đã xuất lên repo công khai** — kiểm tra `.gitignore`
trước khi push.