outlookcli

通过Microsoft Graph为Microsoft Outlook提供生产就绪的CLI和MCP服务器。

github： https://github.com/selvin-paul-raj/outlook-cli

______________________________________________________________________

这个包裹能给你什么

全局CLI命令： outlook-cli
一次性OAuth令牌存储——在运行和更新过程中重复使用
人性化的命令，具有丰富的终端输出、主题预设和机器友好性 --json/--ai 模式
Claude和其他AI助手可以通过共享工具注册表使用21个MCP工具
通过Microsoft Graph API进行完整的电子邮件、日历、文件夹和规则管理

______________________________________________________________________

安装

全球（推荐）

npm i -g outlook-cli

outlook-cli --help

本地开发

npm install
npm run cli -- --help

要求： Node.js>=18.0.0

______________________________________________________________________

Azure应用程序安装程序（必需）

在使用此软件包之前，您需要注册Azure应用程序：

首选 portal.azure.com → Azure Active Directory→ 应用注册→ 新注册
将重定向URI设置为： http://localhost:3333/auth/callback
在“API权限”下，添加Microsoft Graph委派权限：

- Mail.Read, Mail.ReadWrite, Mail.Send - Calendars.Read, Calendars.ReadWrite - User.Read - offline_access

证书和秘密→ 新客户端机密--复制价值（不是秘密ID）
从“概述”页面复制您的应用程序（客户端）ID

______________________________________________________________________

快速开始

1.设置凭据

PowerShell（Windows）：

$env:OUTLOOK_CLIENT_ID="your-client-id-here"
$env:OUTLOOK_CLIENT_SECRET="your-client-secret-value-here"

Bash/zsh（Linux/Mac）：

export OUTLOOK_CLIENT_ID="your-client-id-here"
export OUTLOOK_CLIENT_SECRET="your-client-secret-value-here"

或者使用 .env 文件（复制自 .env.example):

cp .env.example .env
# Edit .env with your credentials

2.启动身份验证服务器（首次登录时需要）

npm run auth-server
# or
outlook-cli auth server --start

这将在端口3333上启动OAuth回调服务器。在身份验证期间保持其运行。

3.认证一次

outlook-cli auth login --open --start-server --wait

这将打开您的浏览器，进入Microsoft登录页面。批准后，令牌将保存到 ~/.outlook-mcp-tokens.json 并在未来的所有运行中重复使用。

4.验证和探索

outlook-cli auth status        # confirm authenticated
outlook-cli tools list         # see all available tools
outlook-cli email list         # list recent inbox emails
outlook-cli calendar list      # list upcoming events

______________________________________________________________________

环境变量

必需

变量	描述
`OUTLOOK_CLIENT_ID`	Azure应用程序应用程序（客户端）ID
`OUTLOOK_CLIENT_SECRET`	Azure应用程序客户端机密价值（不是秘密ID）

可选的

变量	默认值	描述
`OUTLOOK_REDIRECT_URI`	`http://localhost:3333/auth/callback`	OAuth重定向URL
`OUTLOOK_SCOPES`	`offline_access Mail.Read Mail.ReadWrite Mail.Send User.Read Calendars.Read Calendars.ReadWrite`	Microsoft Graph权限范围
`OUTLOOK_TOKEN_STORE_PATH`	`~/.outlook-mcp-tokens.json`	令牌保存在磁盘上的位置
`OUTLOOK_TOKEN_ENDPOINT`	Microsoft消费者OAuth端点	令牌交换URL
`OUTLOOK_AUTH_SERVER_URL`	`http://localhost:3333`	身份验证服务器基本URL
`USE_TEST_MODE`	`false`	使用模拟数据而不是真正的API调用

遗留别名 （向后兼容）： MS_CLIENT_ID, MS_CLIENT_SECRET, MS_REDIRECT_URI, MS_SCOPES, MS_TOKEN_STORE_PATH, MS_TOKEN_ENDPOINT, MS_AUTH_SERVER_URL

______________________________________________________________________

命令组

`auth` --身份验证

命令	描述	示例
`auth status`	显示当前身份验证状态	`outlook-cli auth status`
`auth login`	启动身份验证流程	`outlook-cli auth login --open --start-server --wait`
`auth url`	在不打开浏览器的情况下显示OAuth URL	`outlook-cli auth url`
`auth server`	检查/启动本地OAuth回调服务器	`outlook-cli auth server --start`
`auth logout`	清除存储的令牌	`outlook-cli auth logout`

旗帜 auth login:

--open --在浏览器中自动打开身份验证URL
--start-server --自动启动OAuth回调服务器
--wait --返回前等待身份验证完成
--client-id --在运行时提供应用程序（客户端）ID（可选）
--client-secret --在运行时提供客户端机密值（可选）
--prompt-credentials --提示交互式终端中缺少凭据

示例：

# Full login with browser open and wait
outlook-cli auth login --open --start-server --wait

# Just get the URL to open manually
outlook-cli auth url

# Check if you're logged in
outlook-cli auth status

# Force re-authentication
outlook-cli auth login --open --force

# Runtime credentials (useful outside repo where .env is not loaded)
outlook-cli auth login --open --client-id  --client-secret 

# Start or check auth callback server
outlook-cli auth server --start
outlook-cli auth server --status

______________________________________________________________________

`email` --电子邮件管理

命令	描述	示例
`email list`	列出最近的电子邮件	`outlook-cli email list --count 20`
`email search`	按条件搜索电子邮件	`outlook-cli email search --from boss@company.com`
`email read`	阅读完整的电子邮件内容	`outlook-cli email read --id AAMkAGVm...`
`email attachments`	在一封电子邮件中列出附件	`outlook-cli email attachments --id AAMkAGVm...`
`email attachment`	获取一个附件并可选择保存	`outlook-cli email attachment --id AAMkAGVm... --attachment-id AA... --save-path ./downloads/`
`email send`	发送新电子邮件	`outlook-cli email send --to user@example.com --subject "Hi" --body "Hello"`
`email mark-read`	将电子邮件标记为已读或未读	`outlook-cli email mark-read --id AAMkAGVm...`

______________________________________________________________________

`email list` --列出最近的电子邮件

列出文件夹中的电子邮件，按最新邮件排序。

参数：

标志	类型	默认值	描述
`--folder`	字符串	`inbox`	要列出的文件夹： `inbox`, `sent`, `drafts`, `deleted`, `junk`, `archive`，或任何自定义文件夹名称
`--count`	编号	`10`	要返回的电子邮件数量（1-50）

示例：

# Default: 10 most recent inbox emails
outlook-cli email list

# Last 25 inbox emails
outlook-cli email list --count 25

# 10 most recent sent emails
outlook-cli email list --folder sent

# 15 emails from a custom folder
outlook-cli email list --folder "Project Alpha" --count 15

# Output as JSON for scripting
outlook-cli email list --count 5 --json

输出显示： 电子邮件ID、发件人、主题、日期、已读/未读状态、附件指示器、正文预览。

______________________________________________________________________

`email search` --搜索电子邮件

使用文本和/或筛选条件搜索电子邮件。同时支持多个条件。

参数：

标志	类型	描述
`--query`	string	跨主题、正文和发件人的全文搜索
`--folder`	string	要搜索的文件夹（默认值： `inbox`)
`--from`	string	按发件人电子邮件或姓名筛选
`--to`	string	按收件人电子邮件筛选
`--subject`	string	按主题文本筛选
`--hasAttachments`	boolean	仅显示带附件的电子邮件
`--unreadOnly`	boolean	仅显示未读电子邮件
`--count`	number	最大结果（1–50，默认值：10）

示例：

# Search by keyword
outlook-cli email search --query "quarterly report"

# Find unread emails from a specific sender
outlook-cli email search --from manager@company.com --unreadOnly

# Find emails with attachments about invoices
outlook-cli email search --subject invoice --hasAttachments

# Search sent folder for emails to a client
outlook-cli email search --folder sent --to client@example.com

# Complex search
outlook-cli email search --from finance@company.com --subject "budget" --unreadOnly --count 20

# JSON output
outlook-cli email search --query "meeting notes" --json

______________________________________________________________________

`email read` --阅读完整电子邮件

通过ID读取一封电子邮件的完整内容。

参数：

标志	类型	必填	描述
`--id`	string	yes	来自的电子邮件ID `email list` 或 `email search` 输出

示例：

# Read a specific email
outlook-cli email read --id AAMkAGVmMDAwAT...

# Read and output as JSON
outlook-cli email read --id AAMkAGVmMDAwAT... --json

输出显示： 发件人、收件人、抄送、密件抄送、主题、日期、重要性、附件状态、全文（HTML自动转换为纯文本）。

提示： 从获取电子邮件ID email list 或 email search 输出第一。

______________________________________________________________________

`email attachments` --列出电子邮件附件

列出特定电子邮件的附件。

参数：

标志	类型	必填	默认	描述
`--id`	string	yes	--	来自的消息ID `email list` 或 `email search`
`--count`	编号	否	`25`	列表的最大附件数（1-50）

示例：

# List attachments for one message
outlook-cli email attachments --id AAMkAGVmMDAwAT...

# Limit to first 10 attachments
outlook-cli email attachments --id AAMkAGVmMDAwAT... --count 10

输出显示： 附件ID，类型(fileAttachment, itemAttachment，或 referenceAttachment)、内容类型、大小、内联标志和上次修改日期。

______________________________________________________________________

`email attachment` --获取/下载一个附件

获取一个附件的元数据，并可选择将其保存到磁盘。

参数：

标志	类型	必填	默认	描述
`--id`	string	是	--	消息ID
`--attachmentId`	string	yes	--	附件ID来自 `email attachments`
`--savePath`	string	no	--	保存下载字节的文件路径或目录路径
`--includeContent`	boolean	否	`false`	当附件内容为文本时，包括文本预览
`--expandItem`	boolean	否	`false`	展开项目附件的元数据
`--overwrite`	boolean	否	`false`	覆盖目标路径中的现有文件

示例：

# Get metadata only
outlook-cli email attachment --id AAMkAGVmMDAwAT... --attachment-id AAMkAGVmMDAwAT...=

# Save attachment to downloads directory
outlook-cli email attachment \
  --id AAMkAGVmMDAwAT... \
  --attachment-id AAMkAGVmMDAwAT...= \
  --save-path ./downloads/

# Save and include text preview when possible
outlook-cli email attachment \
  --id AAMkAGVmMDAwAT... \
  --attachment-id AAMkAGVmMDAwAT...= \
  --save-path ./downloads/ \
  --include-content

笔记：

referenceAttachment 是一个云链接，无法从该端点作为原始字节下载。
项目附件在下载时使用MIME原始内容。

______________________________________________________________________

`email send` --发送电子邮件

从用户帐户撰写并发送电子邮件。

参数：

标志	类型	必填	默认	描述
`--to`	string	yes	--	收件人，逗号分隔为多个
`--subject`	string	是	--	电子邮件主题
`--body`	string	yes	--	电子邮件正文（纯文本或HTML）
`--cc`	string	no	--	抄送收件人，逗号分隔
`--bcc`	string	no	--	密件抄送收件人，逗号分隔
`--importance`	string	否	`normal`	优先级： `normal`, `high`，或 `low`
`--saveToSentItems`	boolean	否	`true`	将副本保存到“已发送”文件夹

示例：

# Simple email
outlook-cli email send \
  --to colleague@company.com \
  --subject "Meeting notes" \
  --body "Here are today's action items..."

# Email to multiple recipients with CC and high priority
outlook-cli email send \
  --to "team@company.com,manager@company.com" \
  --cc hr@company.com \
  --subject "URGENT: System outage" \
  --body "We are investigating..." \
  --importance high

# Email without saving to sent folder
outlook-cli email send \
  --to test@example.com \
  --subject "Test" \
  --body "Hello" \
  --saveToSentItems false

笔记：

当正文包含以下内容时，会自动检测HTML正文 ` --args-json ''


**示例：**

List emails via generic call

outlook-cli call list-emails --args-json '{"folder":"inbox","count":5}'

Send email via generic call

outlook-cli call send-email --args-json '{"to":"user@example.com","subject":"Hi","body":"Hello"}'

With JSON output

outlook-cli call list-events --args-json '{"count":10}' --json


______________________________________________________________________

### `agents` --AI代理指南

显示AI代理的最佳实践命令流（Claude、Codex、VS Code、自动化脚本）。

outlook-cli agents guide


**代理工作流程（推荐）：**

outlook-cli auth status --json outlook-cli tools list --json outlook-cli tools schema send-email --json outlook-cli call list-emails --args-json '{"folder":"inbox","count":5}' --ai


______________________________________________________________________

### `doctor` --诊断

运行一系列诊断检查，并报告哪些工作正常，哪些需要修复。

outlook-cli doctor


检查：Node.js版本、环境变量、令牌文件存在、令牌有效性、服务器连接。

______________________________________________________________________

### `update` --更新CLI

Check for updates

outlook-cli update

Run the update automatically

outlook-cli update --run


或者直接通过npm更新：

npm i -g outlook-cli@latest


______________________________________________________________________

## 输出标志（所有命令）

|标志|描述|
|---|---|
| `--json` |输出原始JSON而不是人类可读的文本|
| `--ai` |JSON模式的代理安全别名（抑制富UI输出）|
| `--theme k9s|ocean|mono` |选择文本输出的颜色主题|
| `--plain` |无颜色或格式|
| `--no-color` |仅禁用颜色|
| `--no-animate` |禁用微调器动画|

在JSON模式下，响应包括：

- `result` （原始MCP工具有效载荷）
- `structured` （标准化的机器友好字段，如 `summary`, `items`，以及解析的元数据）

**示例：**

outlook-cli auth status --json outlook-cli tools list --ai outlook-cli email list --count 10 --json outlook-cli --theme ocean --help outlook-cli calendar list --plain


______________________________________________________________________

## 完整的MCP工具目录

所有21个工具都可以通过共享的MCP工具注册表获得，该注册表由Claude和其他AI助手使用，也可以通过以下方式调用 `outlook-cli call `.

### 身份验证工具

|工具|功能|必需|可选|
|---|---|---|---|
| `about` |返回服务器名称、版本、描述|none|none|
| `authenticate` |启动OAuth流，返回auth URL|none| `force` （布尔值）|
| `check-auth-status` |返回当前身份验证状态|none|none|

### 日历工具

|工具|功能|必需|可选|
|---|---|---|---|
| `list-events` |列出即将发生的日历事件|无| `count` (1–50) |
| `create-event` |创建新事件| `subject`, `start`, `end` | `attendees` （阵列）， `body` |
| `decline-event` |拒绝活动邀请| `eventId` | `comment` |
| `cancel-event` |取消活动并通知与会者| `eventId` | `comment` |
| `delete-event` |以静默方式删除事件| `eventId` |没有|

### 电子邮件工具

|工具|功能|必需|可选|
|---|---|---|---|
| `list-emails` |列出文件夹中最近的电子邮件|无| `folder`, `count` |
| `search-emails` |使用文本和筛选条件搜索|无| `query`, `folder`, `from`, `to`, `subject`, `hasAttachments`, `unreadOnly`, `count` |
| `read-email` |阅读一封电子邮件的全部内容| `id` |没有|
| `list-attachments` |列出邮件中的附件| `messageId` | `count` |
| `get-attachment` |获取一个附件元数据，并可选择下载| `messageId`, `attachmentId` | `savePath`, `includeContent`, `expandItem`, `overwrite` |
| `send-email` |发送新电子邮件| `to`, `subject`, `body` | `cc`, `bcc`, `importance`, `saveToSentItems` |
| `mark-as-read` |将电子邮件标记为已读或未读| `id` | `isRead` （布尔值，默认值 `true`) |

### 文件夹工具

|工具|功能|必需|可选|
|---|---|---|---|
| `list-folders` |列出所有邮件文件夹|无| `includeItemCounts`, `includeChildren` |
| `create-folder` |创建新文件夹| `name` | `parentFolder` |
| `move-emails` |将电子邮件移动到另一个文件夹| `emailIds` （逗号分隔）， `targetFolder` | `sourceFolder` |

### 规则工具

|工具|功能|必需|可选|
|---|---|---|---|
| `list-rules` |按执行顺序列出收件箱规则|无| `includeDetails` |
| `create-rule` |创建收件箱规则（1个条件+1个最小操作）| `name` +条件+行动| `isEnabled`, `sequence` |
| `edit-rule-sequence` |更改规则执行顺序| `ruleName`, `sequence` |没有|

______________________________________________________________________

## MCP服务器模式（适用于Claude和AI助手）

作为标准MCP stdio服务器运行，与Claude Desktop或其他MCP客户端一起使用：

npm run mcp-server

or

node index.js


### Claude桌面配置

添加到您的Claude Desktop配置文件(`claude-config-sample.json` 作为参考）：

{ "mcpServers": { "outlook": { "command": "node", "args": ["/path/to/outlook-mcp/index.js"], "env": { "OUTLOOK_CLIENT_ID": "your-client-id", "OUTLOOK_CLIENT_SECRET": "your-client-secret" } } } }


或者，如果全局安装：

{ "mcpServers": { "outlook": { "command": "outlook-cli", "args": ["mcp-server"], "env": { "OUTLOOK_CLIENT_ID": "your-client-id", "OUTLOOK_CLIENT_SECRET": "your-client-secret" } } } }


### AI助手技能

AI助手（Claude和其他人）的完整技能参考见 [技能/前景-mcp.md](skill/outlook-mcp.md)本文档涵盖了每个工具、每个参数、常见工作流程和示例，可用于RAG系统或作为系统提示添加。

______________________________________________________________________

## 代币行为

- 代币存储在 `~/.outlook-mcp-tokens.json` （Windows： `%USERPROFILE%\.outlook-mcp-tokens.json`)
- 令牌在包更新和重新安装后仍然有效——升级后无需重新进行身份验证
- 访问令牌过期时自动刷新（使用刷新令牌）
- 随时强制重新身份验证 `outlook-cli auth login --force` 或 `authenticate { force: true }`

______________________________________________________________________

## 测试模式

USE_TEST_MODE=true outlook-cli email list


随着 `USE_TEST_MODE=true`，所有API调用都使用模拟数据-不需要真正的Microsoft帐户。可用于开发和CI测试。

______________________________________________________________________

## 故障排除

|问题|解决方案|
|---|---|
| `AADSTS7000215` 错误|您使用的是机密ID而不是机密 **价值** 在Azure中|
|身份验证服务器无法启动|运行 `npx kill-port 3333` 然后再试一次|
|令牌存在后“未通过身份验证”|令牌过期，没有刷新令牌--运行 `auth login` 再一次|
| `create-rule` 在文件夹上失败|文件夹不存在--运行 `folder create` 首先|
| `move-emails` 部分失败|某些电子邮件ID无效--使用验证ID `email list` |
|缺少依赖项|运行 `npm install` |

______________________________________________________________________

## AI助手技能

这 `skills/outlook-automation/` 文件夹包含Claude Code、OpenAI Codex和VS Code的结构化技能。

### 安装技能

Claude Code — personal

uv run python tools/install_skill.py --personal

Claude Code — project/team

uv run python tools/install_skill.py --project

OpenAI Codex

uv run python tools/install_skill.py --codex

Verify

uv run python tools/install_skill.py --verify --personal


> **注：** OpenAI Codex技能需要实验功能标志。添加 `~/.codex/config.toml`:
>
> ```toml
> [features]
> skills = true
> ```

### 技能结构

|文件|内容|
|---|---|
| [技能/前景自动化/SKILL.md](skills/outlook-automation/SKILL.md) |主要技能条目——概述、行为规则、快速示例、安装说明|
| [技能/前景自动化/参考/cli.md](skills/outlook-automation/reference/cli.md) |完整的CLI命令参考——每个命令、标志和示例|
| [技能/前景自动化/参考/json-schema.md](skills/outlook-automation/reference/json-schema.md) |所有21个MCP工具的JSON模式|
| [技能/前景自动化/参考/安全.md](skills/outlook-automation/reference/security.md) |OAuth流程、令牌生命周期、权限范围、AI安全规则|
| [技能/前景自动化/参考/故障排除.md](skills/outlook-automation/reference/troubleshooting.md) |常见错误、诊断清单、逐步修复|

______________________________________________________________________

## 文档

|文件|内容|
|---|---|
| [文档/参考.md](docs/REFERENCE.md) |全参数逐参数API参考|
| [CLI.md](CLI.md) |CLI快速参考卡|
| [QUICKSTART.md](QUICKSTART.md) |新用户设置演练|
| [文档/项目结构.md](docs/PROJECT-STRUCTURE.md) |代码库架构和模块概述|
| [docs/PUBLISHING.md](docs/PUBLISHING.md) |发布维护人员检查表|
| [claude-config-sample.json](claude-config-sample.json) |克劳德桌面MCP配置示例|

______________________________________________________________________

## 脚本参考

|脚本|命令|描述|
|---|---|---|
| `npm start` | `node cli.js` |运行CLI|
| `npm run mcp-server` | `node index.js` |以MCP stdio服务器运行|
| `npm run cli` | `node cli.js` |CLI别名|
| `npm run auth-server` | `node outlook-auth-server.js` |在端口3333上启动OAuth回调服务器|
| `npm run doctor` | `node cli.js doctor` |运行诊断程序|
| `npm run inspect` |MCP检查器|交互式测试MCP服务器|
| `npm test` |Jest |运行单元测试|

Outlook CLI

快速接入

详细介绍

outlookcli

这个包裹能给你什么

安装

全球（推荐）

本地开发

Azure应用程序安装程序（必需）

快速开始

1.设置凭据

2.启动身份验证服务器（首次登录时需要）

3.认证一次

4.验证和探索

环境变量

必需

可选的

命令组

auth --身份验证

email --电子邮件管理

email list --列出最近的电子邮件

email search --搜索电子邮件

email read --阅读完整电子邮件

email attachments --列出电子邮件附件

email attachment --获取/下载一个附件

email send --发送电子邮件

List emails via generic call

Send email via generic call

With JSON output

Check for updates

Run the update automatically

or

Claude Code — personal

Claude Code — project/team

OpenAI Codex

Verify

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`auth` --身份验证

`email` --电子邮件管理

`email list` --列出最近的电子邮件

`email search` --搜索电子邮件

`email read` --阅读完整电子邮件

`email attachments` --列出电子邮件附件

`email attachment` --获取/下载一个附件

`email send` --发送电子邮件