Outlook Skill
Access Outlook/Hotmail email and calendar via Microsoft Graph API using OAuth2.
Quick Setup (Automated)
CODEBLOCK0
The setup script will:
- 1. Log you into Azure (device code flow)
- Create an App Registration automatically
- Configure API permissions (Mail.ReadWrite, Mail.Send, Calendars.ReadWrite)
- Guide you through authorization
- Save credentials to INLINECODE0
Manual Setup
See references/setup.md for step-by-step manual configuration via Azure Portal.
Usage
Token Management
CODEBLOCK1
Reading Emails
CODEBLOCK2
Managing Emails
CODEBLOCK3
Sending Emails
CODEBLOCK4
Folders & Stats
CODEBLOCK5
Calendar
Viewing Events
CODEBLOCK6
Creating Events
CODEBLOCK7
Managing Events
CODEBLOCK8
Date format: YYYY-MM-DDTHH:MM (e.g., 2026-01-26T10:00)
Example Output
CODEBLOCK9
Token Refresh
Access tokens expire after ~1 hour. Refresh with:
CODEBLOCK10
Files
- -
~/.outlook-mcp/config.json - Client ID and secret - INLINECODE5 - OAuth tokens (access + refresh)
Permissions
- -
Mail.ReadWrite - Read and modify emails - INLINECODE7 - Send emails
- INLINECODE8 - Read and modify calendar events
- INLINECODE9 - Refresh tokens (stay logged in)
- INLINECODE10 - Basic profile info
Notes
- - Email IDs: The
id field shows the last 20 characters of the full message ID. Use this ID with commands like read, mark-read, delete, etc. - Numbered results: Emails are numbered (n: 1, 2, 3...) for easy reference in conversation.
- Text extraction: HTML email bodies are automatically converted to plain text.
- Token expiry: Access tokens expire after ~1 hour. Run
outlook-token.sh refresh when you see auth errors. - Recent emails: Commands like
read, mark-read, etc. search the 100 most recent emails for the ID.
Troubleshooting
"Token expired" → Run INLINECODE18
"Invalid grant" → Token invalid, re-run setup: INLINECODE19
"Insufficient privileges" → Check app permissions in Azure Portal → API Permissions
"Message not found" → The email may be older than 100 messages. Use search to find it first.
"Folder not found" → Use exact folder name. Run folders to see available folders.
Supported Accounts
- - Personal Microsoft accounts (outlook.com, hotmail.com, live.com)
- Work/School accounts (Microsoft 365) - may require admin consent
Changelog
v1.3.0
- - Added: Calendar support (
outlook-calendar.sh)
- View events (today, week, upcoming)
- Create/quick-create events
- Update event details (subject, location, time)
- Delete events
- Check availability (free/busy)
- List calendars
- - Added:
Calendars.ReadWrite permission
v1.2.0
- - Added:
mark-unread - Mark emails as unread - Added:
flag/unflag - Flag/unflag emails as important - Added:
delete - Move emails to trash - Added:
archive - Archive emails - Added:
move - Move emails to any folder - Added:
from - Filter emails by sender - Added:
attachments - List email attachments - Added:
reply - Reply to emails - Improved:
send - Better error handling and status output - Improved:
move - Case-insensitive folder names, shows available folders on error
v1.1.0
- - Fixed: Email IDs now use unique suffixes (last 20 chars)
- Added: Numbered results (n: 1, 2, 3...)
- Improved: HTML bodies converted to plain text
- Added:
to field in read output
v1.0.0
Outlook 技能
通过 Microsoft Graph API 使用 OAuth2 访问 Outlook/Hotmail 电子邮件和日历。
快速设置（自动化）
bash
需要：Azure CLI, jq
./scripts/outlook-setup.sh
设置脚本将：
- 1. 登录 Azure（设备代码流程）
- 自动创建应用注册
- 配置 API 权限（Mail.ReadWrite、Mail.Send、Calendars.ReadWrite）
- 引导您完成授权
- 将凭据保存到 ~/.outlook-mcp/
手动设置
请参阅 references/setup.md，了解通过 Azure 门户进行逐步手动配置的说明。
使用方法
令牌管理
bash
./scripts/outlook-token.sh refresh # 刷新过期令牌
./scripts/outlook-token.sh test # 测试连接
./scripts/outlook-token.sh get # 打印访问令牌
阅读电子邮件
bash
./scripts/outlook-mail.sh inbox [count] # 列出最新邮件（默认：10）
./scripts/outlook-mail.sh unread [count] # 列出未读邮件
./scripts/outlook-mail.sh search query [count] # 搜索邮件
./scripts/outlook-mail.sh from
[count] # 列出来自发件人的邮件
./scripts/outlook-mail.sh read # 阅读邮件内容
./scripts/outlook-mail.sh attachments # 列出邮件附件
管理电子邮件
bash
./scripts/outlook-mail.sh mark-read # 标记为已读
./scripts/outlook-mail.sh mark-unread # 标记为未读
./scripts/outlook-mail.sh flag # 标记为重要
./scripts/outlook-mail.sh unflag # 取消标记
./scripts/outlook-mail.sh delete # 移至垃圾箱
./scripts/outlook-mail.sh archive # 移至归档
./scripts/outlook-mail.sh move # 移至文件夹
发送电子邮件
bash
./scripts/outlook-mail.sh send # 发送新邮件
./scripts/outlook-mail.sh reply body # 回复邮件
文件夹与统计
bash
./scripts/outlook-mail.sh folders # 列出邮件文件夹
./scripts/outlook-mail.sh stats # 收件箱统计
日历
查看事件
bash
./scripts/outlook-calendar.sh events [count] # 列出即将发生的事件
./scripts/outlook-calendar.sh today # 今日事件
./scripts/outlook-calendar.sh week # 本周事件
./scripts/outlook-calendar.sh read # 事件详情
./scripts/outlook-calendar.sh calendars # 列出所有日历
./scripts/outlook-calendar.sh free # 检查空闲状态
创建事件
bash
./scripts/outlook-calendar.sh create [location] # 创建事件
./scripts/outlook-calendar.sh quick [time] # 快速创建1小时事件
管理事件
bash
./scripts/outlook-calendar.sh update # 更新（主题/地点/开始/结束）
./scripts/outlook-calendar.sh delete # 删除事件
日期格式：YYYY-MM-DDTHH:MM（例如：2026-01-26T10:00）
示例输出
bash
$ ./scripts/outlook-mail.sh inbox 3
{
n: 1,
subject: 您的每周摘要,
from: digest@example.com,
date: 2026-01-25T15:44,
read: false,
id: icYY6QAIUE26PgAAAA==
}
{
n: 2,
subject: 会议提醒,
from: calendar@outlook.com,
date: 2026-01-25T14:06,
read: true,
id: icYY6QAIUE26PQAAAA==
}
$ ./scripts/outlook-mail.sh read icYY6QAIUE26PgAAAA==
{
subject: 您的每周摘要,
from: { name: 摘要, address: digest@example.com },
to: [you@hotmail.com],
date: 2026-01-25T15:44:00Z,
body: 以下是本周发生的事情...
}
$ ./scripts/outlook-mail.sh stats
{
folder: 收件箱,
total: 14098,
unread: 2955
}
$ ./scripts/outlook-calendar.sh today
{
n: 1,
subject: 团队站会,
start: 2026-01-25T10:00,
end: 2026-01-25T10:30,
location: Teams,
id: AAMkAGQ5NzE4YjQ3...
}
$ ./scripts/outlook-calendar.sh create 与客户午餐 2026-01-26T13:00 2026-01-26T14:00 餐厅
{
status: 事件已创建,
subject: 与客户午餐,
start: 2026-01-26T13:00,
end: 2026-01-26T14:00,
id: AAMkAGQ5NzE4YjQ3...
}
令牌刷新
访问令牌约1小时后过期。使用以下命令刷新：
bash
./scripts/outlook-token.sh refresh
文件
- - ~/.outlook-mcp/config.json - 客户端ID和密钥
- ~/.outlook-mcp/credentials.json - OAuth令牌（访问 + 刷新）
权限
- - Mail.ReadWrite - 读取和修改电子邮件
- Mail.Send - 发送电子邮件
- Calendars.ReadWrite - 读取和修改日历事件
- offline_access - 刷新令牌（保持登录状态）
- User.Read - 基本个人资料信息
注意事项
- - 邮件ID：id字段显示完整消息ID的最后20个字符。在read、mark-read、delete等命令中使用此ID。
- 编号结果：邮件按编号（n: 1, 2, 3...）显示，便于在对话中引用。
- 文本提取：HTML邮件正文会自动转换为纯文本。
- 令牌过期：访问令牌约1小时后过期。当看到认证错误时，运行outlook-token.sh refresh。
- 最近邮件：read、mark-read等命令会在最近的100封邮件中搜索ID。
故障排除
令牌已过期 → 运行 outlook-token.sh refresh
授权无效 → 令牌无效，重新运行设置：outlook-setup.sh
权限不足 → 在Azure门户中检查应用权限 → API权限
未找到消息 → 邮件可能早于最近的100条。先使用搜索功能查找。
未找到文件夹 → 使用准确的文件夹名称。运行folders查看可用文件夹。
支持的账户
- - 个人Microsoft账户（outlook.com、hotmail.com、live.com）
- 工作/学校账户（Microsoft 365）- 可能需要管理员同意
更新日志
v1.3.0
- - 新增：日历支持（outlook-calendar.sh）
- 查看事件（今日、本周、即将发生）
- 创建/快速创建事件
- 更新事件详情（主题、地点、时间）
- 删除事件
- 检查空闲状态（空闲/忙碌）
- 列出日历
- - 新增：Calendars.ReadWrite 权限
v1.2.0
- - 新增：mark-unread - 将邮件标记为未读
- 新增：flag/unflag - 标记/取消标记邮件为重要
- 新增：delete - 将邮件移至垃圾箱
- 新增：archive - 归档邮件
- 新增：move - 将邮件移至任意文件夹
- 新增：from - 按发件人筛选邮件
- 新增：attachments - 列出邮件附件
- 新增：reply - 回复邮件
- 改进：send -
