# MCP Outlook

一个面向 Windows 桌面版 Microsoft Outlook 的本地
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器。
它通过 Outlook COM 接口让支持 MCP 的 AI 客户端读取、搜索和整理邮件，
并以“先创建草稿、再显式发送”的方式辅助撰写回复或新邮件。

项目支持 stdio 与 Streamable HTTP 两种传输模式，无需 Microsoft Graph
或云端邮件 API。邮件数据默认在本机处理，适合个人办公自动化、邮件检索、
草稿生成和 AI Agent 工作流。

## 功能

- 获取邮件列表，支持文件夹、分页和未读状态筛选
- 读取纯文本或 HTML 邮件正文及附件元数据
- 按主题、发件人、正文、日期、附件和重要性搜索邮件
- 标记已读/未读、移动和删除邮件
- 创建回复、回复全部、转发或全新邮件草稿
- 使用 Markdown 生成 Outlook/Word 兼容的 HTML 正文
- 搜索联系人、查看发件人信息和展开通讯组
- 递归列出或创建 Outlook 文件夹
- 记录敏感写操作的审计日志
- 提供健康检查、运行指标和可选的 HTTP API Key 鉴权
- 自动重试临时 COM 错误并周期性回收连接

## 运行要求

- Windows 10 或 Windows 11
- Python 3.10+
- 已安装并配置 Microsoft Outlook 桌面版
- Outlook 配置文件中已有可访问的邮箱

> [!IMPORTANT]
> 本项目使用 Windows COM，因此不能直接运行在 Linux、macOS、GitHub
> Codespaces 或普通 Linux 容器中。运行服务的 Windows 用户必须能够正常启动
> Outlook。

## 快速开始

### 1. 克隆并安装

```powershell
git clone https://github.com/<your-account>/mcp-outlook.git
Set-Location mcp-outlook

python -m venv venv
.\venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

如果 PowerShell 禁止执行虚拟环境激活脚本，可以不激活环境，直接使用
`.\venv\Scripts\python.exe` 执行后续命令。

### 2. 创建配置

```powershell
Copy-Item .env.example .env
```

默认配置只监听 `127.0.0.1:8000`。常用配置项如下：

| 环境变量 | 默认值 | 说明 |
|---|---:|---|
| `MCP_OUTLOOK_HOST` | `127.0.0.1` | HTTP 监听地址 |
| `MCP_OUTLOOK_PORT` | `8000` | HTTP 监听端口 |
| `MCP_OUTLOOK_LOG_LEVEL` | `INFO` | 日志级别 |
| `MCP_OUTLOOK_LOG_FILE` | `logs/mcp-outlook.log` | 运行日志路径 |
| `MCP_OUTLOOK_DEFAULT_EMAIL_LIMIT` | `50` | 默认邮件返回数量 |
| `MCP_OUTLOOK_MAX_EMAIL_LIMIT` | `200` | 单次查询最大数量 |
| `MCP_OUTLOOK_COM_RECYCLE_INTERVAL` | `100` | COM 连接回收间隔，`0` 表示不自动回收 |
| `MCP_OUTLOOK_API_KEY` | 空 | HTTP 模式的可选 API Key |

`.env`、日志、审计记录和虚拟环境均已加入 `.gitignore`，不要将真实凭据或邮件
数据提交到仓库。

## 启动方式

### stdio 模式

stdio 适合由本机 MCP 客户端直接启动，不需要开放网络端口。

```json
{
  "mcpServers": {
    "outlook": {
      "command": "C:\\path\\to\\mcp-outlook\\venv\\Scripts\\python.exe",
      "args": ["-m", "src.mcp_outlook.server"],
      "cwd": "C:\\path\\to\\mcp-outlook",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "PYTHONPATH": "C:\\path\\to\\mcp-outlook"
      }
    }
  }
}
```

将示例中的 `C:\path\to\mcp-outlook` 替换为仓库的实际绝对路径，然后重启
MCP 客户端。

### HTTP 模式

使用默认的本地监听配置启动：

```powershell
$env:MCP_TRANSPORT = "http"
.\venv\Scripts\python.exe -m src.mcp_outlook.server
```

也可以运行项目脚本：

```powershell
.\start-network.bat
```

`start-network.bat` 会监听 `0.0.0.0:8000`，用于局域网或隧道场景。启用网络访问
前，建议在 `.env` 中配置高强度的 `MCP_OUTLOOK_API_KEY`，并使用防火墙限制来源。

HTTP 端点：

| 地址 | 用途 |
|---|---|
| `http://127.0.0.1:8000/mcp` | MCP Streamable HTTP |
| `http://127.0.0.1:8000/health` | Outlook 连接与服务健康状态 |
| `http://127.0.0.1:8000/metrics` | 工具调用和进程指标 |

配置 API Key 后，请求 `/mcp` 和 `/metrics` 时需要提供
`X-API-Key` 请求头；`/health` 保持可用于健康探测。

## 可用工具

| 类别 | 工具 |
|---|---|
| 阅读与搜索 | `get_emails`、`read_email`、`search_emails`、`search_by_subject`、`search_by_sender`、`search_by_content` |
| 邮件操作 | `mark_as_read`、`move_email`、`delete_email` |
| 草稿与发送 | `create_reply_draft`、`create_forward_draft`、`create_new_draft`、`update_draft`、`send_draft` |
| 联系人与文件夹 | `get_sender_details`、`search_contacts`、`expand_distribution_list`、`list_folders`、`create_folder` |
| 运维与审计 | `get_recent_actions`、`restart_outlook` |

完整参数、返回结构和调用示例请参阅
[MCP 工具接口规范](docs/design/api/tools-api.md)。

## 安全设计

- 默认仅监听本机回环地址
- HTTP 模式支持 API Key
- 创建和修改邮件时默认保存为草稿，发送需要单独调用 `send_draft`
- 删除、移动、发送和草稿修改等操作写入本地审计日志
- 查询字符串在进入 Outlook DASL/Jet 查询前进行转义
- 日志、审计数据和 `.env` 不纳入版本控制

MCP 客户端仍可能读取或修改真实邮箱。请仅向可信客户端开放服务，并在发送、
删除或批量移动邮件前确认操作参数。

## 开发与测试

```powershell
.\venv\Scripts\python.exe -m unittest discover -s tests -v
```

项目结构：

```text
src/mcp_outlook/   Outlook COM、MCP 工具、配置、日志与服务入口
tests/             标准库 unittest 测试
docs/              需求、架构、模块设计与 API 规范
```

更多设计资料见 [docs/design/README.md](docs/design/README.md)。

## 已知限制

- 仅支持 Windows 桌面版 Outlook，不支持新版 Outlook WebView 客户端或 Outlook Web
- 邮件移动到其他文件夹后，Outlook `EntryID` 可能发生变化
- COM 操作依赖当前 Windows 用户会话和 Outlook 配置文件
- 在无人登录的 Windows 服务会话中运行 Outlook COM 可能不稳定

## License

本仓库尚未包含开源许可证文件。公开发布前请根据实际使用计划补充许可证。