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

Install / Cài đặt

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:

{
  "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.

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.