内容
# outlook-mcp-server
一款适用于个人微软Outlook/Hotmail账户的轻量级[模型上下文协议（MCP）](https://modelcontextprotocol.io)服务器。它通过微软图形API使用OAuth 2.0设备代码流将Claude（或任何MCP兼容的AI）连接到您的收件箱，无需服务账户或管理员同意。
## 工具列表
| 工具 | 参数 | 描述 |
|---|---|---|
| `search_emails` | `query`, `max_results` | 使用KQL（关键词查询语言）搜索您的收件箱。支持按发件人、主题、日期、附件存在等条件筛选。 |
| `read_email` | `message_id` | 获取特定邮件的全文（纯文本+HTML）和头部信息。 |
| `list_attachments` | `message_id` | 列出邮件的所有附件，包括其ID、名称、大小和内容类型。 |
| `download_attachment` | `message_id`, `attachment_id`, `save_path` | 下载附件并保存到本地文件路径。 |
| `mark_as_read` | `message_id`, `read` | 将邮件标记为已读或未读。 |
| `move_email` | `message_id`, `folder` | 将邮件移动到具有已知名称（例如`inbox`, `deleteditems`, `archive`）或文件夹ID的文件夹。 |
这些工具可以自然地组合成电子邮件自动化工作流程——例如：按发件人搜索→读取正文→下载附件→标记为已读→移动到存档。
## 设置
### 1. Azure应用注册（一次性）
个人微软账户仍然需要Azure应用注册才能调用图形。
1. 前往 <https://portal.azure.com> → **微软Entra ID** → **应用注册** → **新建注册**。
2. 名称：`outlook-mcp-server`（或任意名称）。
3. **支持的账户类型**：选择**“仅限个人微软账户”**。
4. **重定向URI**：暂时留空。
5. 创建后，复制**应用程序（客户端）ID** —— 这是您的 `OUTLOOK_MCP_CLIENT_ID`。
6. 打开 **身份验证** → 启用 **“允许公共客户端流”** = **是** → 保存。
7. 打开 **API权限** → **添加权限** → **微软图形** → **委托权限** → 选中 **`Mail.ReadWrite`** → **添加**。（个人账户无需管理员同意。）
### 2. 安装
```bash
git clone https://github.com/dhtim135/outlook-mcp-server
cd outlook-mcp-server
uv sync
```
### 3. 身份验证（一次性）
```bash
export OUTLOOK_MCP_CLIENT_ID="<your-client-id>"
uv run python login.py
```
按照设备代码提示 —— 在任意浏览器中访问URL，输入代码，使用Hotmail/Outlook.com账户登录，并批准 `Mail.ReadWrite` 权限。
令牌缓存在 `~/.config/outlook-mcp/token-cache.json`（模式 0600）。只要服务器至少每90天使用一次，刷新令牌就会自动旋转。
### 4. 注册Claude代码
```bash
claude mcp add outlook \
--env OUTLOOK_MCP_CLIENT_ID="<your-client-id>" \
-- uv --directory /path/to/outlook-mcp-server run python server.py
```
或手动添加到您的MCP配置中：
```json
{
"mcpServers": {
"outlook": {
"command": "uv",
"args": [
"--directory", "/path/to/outlook-mcp-server",
"run", "python", "server.py"
],
"env": {
"OUTLOOK_MCP_CLIENT_ID": "<your-client-id>"
}
}
}
}
```
## KQL搜索示例
```
from:amazon.com
subject:invoice
from:receipts@uber.com received>=2026-01-01
hasattachment:yes from:doordash.com
```
多个术语使用AND运算符连接。引用带有空格的短语。
## 重新身份验证
如果您看到 `Token refresh failed`，只需重新运行 `uv run python login.py`。
