Outlook邮件搜索服务

📬 Outlook MCP Server

Bring your Outlook mailboxes into the Model Context Protocol.
Search, analyze, and surface email chains for AI assistants—with support for personal and shared mailboxes, parallel search, and near-instant AdvancedSearch.

📑 目录

• ✨ 特性
• 📋 需求
• 🚀 快速开始
• 🧪 如何测试
• ⚙️ 配置
• 🔧 工具
• 🔍 搜索与性能
• 🔌 MCP配置
• 📇 启用Outlook搜索（高级搜索）
• 🔧 故障排除
• 📁 项目结构
• 🔒 安全
• 🤝 贡献
• 👤 作者

✨ 特性

• 多邮箱 --访问个人收件箱和一个或多个共享邮箱。
• 高级搜索 --使用Outlook的索引进行快速主题+正文搜索。
• 并行搜索 --同时搜索个人和共享邮箱。
• 全链条 --返回完整的电子邮件正文和对话分组。
• 可配置的 --缓存、工作进程、批大小、重试次数等 config.properties.
• 健康检查 — check_mailbox_access 兼作连接健康检查。

📋 需求

🚀 快速开始

# 1. Clone and enter project
git clone <repository-url>
cd Outlook-MCP-Server

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure (edit shared mailbox and options)
#    File: src/config/config.properties
#    Run from project root so config is found.

# 4. Start the server (with Outlook running)
python outlook_mcp.py

配置路径： 加载自 src/config/config.properties 或从当前工作目录。从项目根目录运行： python outlook_mcp.py.

🧪 如何测试

1.单元测试（不需要Outlook）

在任何操作系统上运行（例如CI中的Linux）。仅测试配置加载和电子邮件格式。逃离 项目根目录 （conftest.py将根添加到路径中）。

cd Outlook-MCP-Server
pip install -r requirements-ci.txt
python -m pytest tests/test_config_reader.py tests/test_email_formatter.py tests/test_tools.py tests/test_get_latest_emails.py -v

如果从其他目录运行，请设置 PYTHONPATH 到项目根（例如。 set PYTHONPATH=. 在Windows cmd上，或 $env:PYTHONPATH="." 在PowerShell上）。

2.连接测试（需要Windows+Outlook）

验证服务器是否可以连接到Outlook并访问邮箱。 需要运行Microsoft Outlook的Windows。

python tests/test_connection.py

出现提示时，如果出现安全对话框，请允许Outlook权限。您可以输入搜索词来测试电子邮件搜索，或按enter键使用默认值。

3.绒毛和类型检查（可选）

pip install -r requirements-dev.txt
python -m flake8 src outlook_mcp.py
python -m mypy src outlook_mcp.py

4.CI

在推送/PR上，GitHub Actions运行：

• 棉绒： flake8和mypy src 和 outlook_mcp.py
• 测验： pytest打开 test_config_reader.py, test_email_formatter.py, test_tools.py，以及 test_get_latest_emails.py （使用 requirements-ci.txt，所以Linux上没有pywin32；工具测试使用模拟的Outlook客户端）

必须在安装了Outlook的Windows上手动完成完整的端到端测试（Outlook连接和搜索）。

⚙️ 配置

所有选项均已启用 config.properties.运行时使用以下命令重新加载 config.reload().

邮箱

搜索

性能和缓存

其他

🔧 工具

1. check_mailbox_access （健康检查）

验证与Outlook的连接以及对已配置邮箱的访问权限。

用作 健康检查 确认服务器可以访问Outlook和共享邮箱。

2. get_email_chain

在中搜索包含给定文本的电子邮件 主体与身体，返回完整的链。

请求示例：

{
  "tool": "get_email_chain",
  "arguments": {
    "search_text": "server error 500",
    "include_personal": true,
    "include_shared": true,
    "include_body": true
  }
}

回复中的每封电子邮件都包括 entry_id.使用它 reply_to_email 和 forward_email.

3. get_latest_emails

返回 N封最近的电子邮件 来自收件箱（无搜索短语）。用于“最后一封电子邮件”、“最近10封电子邮件”，或者当您需要最新消息时，无论内容如何。

例子： get_latest_emails 随着 count: 1 返回您最近的一封收件箱电子邮件。使用 get_email_chain 当你需要按特定短语搜索时。

4. send_email

使用默认Outlook帐户撰写并发送新电子邮件。 立即发送 （无草稿）。发送、回复和转发工具发送 真实电子邮件；小心使用。

5. reply_to_email

回复电子邮件。使用 entry_id 从 get_email_chain 或 get_latest_emails.

6. forward_email

转发电子邮件。使用 entry_id 从 get_email_chain 或 get_latest_emails.

其他可能的功能（未来）

稍后的想法：list_folders、move_email、mark_read/mark_unread、delete_email、get_calendar_event、create_calendar_event，add_attachment、get_tacts、draft_email（创建草稿而不发送）。

🔍 搜索与性能

• 高级搜索 --使用Outlook的索引；主体与身体；不区分大小写的短语匹配；通常为亚秒至几秒。
• 后备方案 --如果AdvancedSearch失败（例如索引关闭），则退回到仅限主题和可选迭代。
• 并行搜索 --可以并行搜索个人邮箱和每个共享邮箱（可配置worker）。
• 缓存 --按查询和邮箱选择缓存的结果；TTL和最大条目可配置。
• 连接 --首先尝试现有Outlook实例；指数回退+重试时的抖动。
• 非阻塞 --所有Outlook工作都通过运行 asyncio.to_thread() 因此MCP服务器保持响应。

提示： 启用Outlook索引；使用特定的搜索词；设定一个合理的 max_search_results；使用 profile_search=true 调音。

🔌 MCP配置

将此服务器添加到您的MCP客户端，以便工具（check_mailbox_access、get_email_chain、get_latest_emails、send_email、reply_to_email和forward_email）可用。使用 完整路径 到你的Python可执行文件和 outlook_mcp.pyOutlook必须在同一台Windows计算机上运行。

克劳德桌面版

编辑MCP配置文件：

• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

添加 outlook 服务器下 mcpServers:

{
  "mcpServers": {
    "outlook": {
      "command": "python",
      "args": ["C:\\Users\\YourName\\Documents\\GitHub\\Outlook-MCP-Server\\outlook_mcp.py"]
    }
  }
}

使用实际路径和双反斜杠(\\)JSON格式。保存后重新启动Claude Desktop。

光标

在光标中： 设置→ 光标设置→ MCP （或直接编辑MCP配置文件）。添加：

{
  "mcpServers": {
    "outlook": {
      "command": "python",
      "args": ["C:\\Users\\YourName\\Documents\\GitHub\\Outlook-MCP-Server\\outlook_mcp.py"]
    }
  }
}

通用MCP配置（任何客户端）

任何支持stdio传输的MCP客户端都可以使用此服务器。将服务器条目放入客户端的MCP配置中：

{
  "mcpServers": {
    "outlook": {
      "command": "C:\\Users\\YourName\\AppData\\Local\\Programs\\Python\\Python311\\python.exe",
      "args": ["C:\\Users\\YourName\\Documents\\GitHub\\Outlook-MCP-Server\\outlook_mcp.py"]
    }
  }
}

• 命令 --完整路径 python.exe （例如来自 where python 在Windows上）。
• 参数 --具有完整路径的数组 outlook_mcp.py 在这个回购中。

服务器通过stdio运行；不需要额外的env变量。在中配置邮箱和选项 src/config/config.properties 在repo文件夹中。

📇 启用Outlook搜索（高级搜索）

如果您在日志中看到“AdvancedSearch不可用”，则服务器将使用回退并仍然返回结果。要使用更快的基于索引的搜索（AdvancedSearch），请启用Outlook索引：

1.Windows搜索服务

1. 按 赢+R，类型 services.msc，按Enter键。
2. 找到 Windows 搜索 在列表中。
3. 右击→ 属性.
4. 集 启动类型 到 自动.
5. 点击 开始 如果服务未运行，则 好的.

2.展望索引

1. 打开 微软Outlook.
2. 文件 → 选项.
3. 首选 搜索 （左侧）。
4. 点击 索引选项 （或 索引).
5. 确保 微软Outlook （以及您的邮件配置文件）位于索引位置列表中。
6. 如果Outlook丢失，请单击 修改 并检查 微软Outlook /那么，您的邮箱 好的.
7. 点击 索引选项 再次执行，然后等待索引完成（对于大型邮箱可能需要一段时间）。

3.重建索引（如果搜索仍然失败）

1. 在 索引选项，单击 高级.
2. 在...之下 故障排除，单击 重建.
3. 确认并等待重建完成（可能需要15+分钟）。
4. 重新启动Outlook，然后重试MCP服务器。

4.重新启动并测试

• 重新启动Outlook（以及正在运行的MCP服务器）。
• 跑 python tests/test_connection.py 并进行搜索。如果AdvancedSearch有效，您将不再在日志中看到“AdvancedSearch不可用”。

🔧 故障排除

调试日志记录：

import logging
logging.basicConfig(level=logging.DEBUG)

📁 项目结构

Outlook-MCP-Server/
├── outlook_mcp.py              # Entrypoint
├── requirements.txt            # mcp, pywin32
├── requirements-ci.txt         # CI (no pywin32)
├── requirements-dev.txt        # flake8, mypy
├── pyproject.toml              # Lint/tool config
├── src/
│   ├── config/
│   │   ├── config_reader.py    # Load, validate, reload
│   │   └── config.properties   # User settings
│   ├── tools/
│   │   └── outlook_tools.py    # MCP tool definitions
│   └── utils/
│       ├── outlook_client.py   # Outlook COM + search + cache
│       └── email_formatter.py  # Format for AI
├── .github/workflows/
│   └── test.yml                # Lint + unit tests
└── tests/
    ├── conftest.py
    ├── test_config_reader.py
    ├── test_email_formatter.py
    ├── test_tools.py             # Tool schemas + call_tool with mocked Outlook
    ├── test_get_latest_emails.py  # get_latest_emails tool only
    └── test_connection.py    # Windows + Outlook

🔒 安全

• 仅限本地 --服务器在本地运行，并通过COM与Outlook通信。
• 没有存储凭据 --使用当前Windows用户的Outlook配置文件。
• 权限对话框 --Windows可能会提示Outlook访问；根据需要允许。
• 日志记录 --在正常操作中不记录电子邮件地址或敏感配置。
• 范围 --仅限于您配置的邮箱（个人+列出的共享）。

🤝 贡献

1. 分叉回购
2. 创建要素分支
3. 进行更改并添加测试（如果适用）
4. 打开拉取请求

📄 许可证

麻省理工学院——见许可证。

🙏 致谢

• 模型上下文协议
• pywin32 用于Outlook COM接口

👤 作者

Hemprasad Badgujar

Outlook MCP服务器 --将Outlook纳入模型上下文协议。