Cowork MCP

Outlook MCP服务器

一个自托管Python MCP服务器，通过Microsoft Graph API为Claude提供对个人Outlook帐户（hotmail.com/Microsoft个人帐户）的完全读/写访问权限。在Cloudflare隧道后面的Ubuntu服务器上持续运行，可通过HTTPS从任何Claude客户端访问。

Claude clients (Claude Code / claude.ai / Cowork on Windows laptop)
        |  HTTPS (Streamable HTTP MCP transport)
        v
Cloudflare Tunnel
        v
Ubuntu Server -- Python MCP Server (FastMCP, port 8000)
        |  Microsoft Graph API (OAuth2 via MSAL)
        v
Personal Outlook account

______________________________________________________________________

先决条件

• Python 3.11+ 在Ubuntu服务器上
• Ubuntu服务器 （VPS、家庭服务器或任何永远在线的Linux机器）
• Cloudflare帐户 （免费等级就足够了；域名是可选的）
• Azure应用程序注册 （一次性手动设置——见下文）

______________________________________________________________________

Azure应用程序注册

这是一个一次性手动步骤，必须在运行服务器之前完成。

1. 首选 https://portal.azure.com → 应用程序注册 → 新注册
2. 姓名： outlook-mcp-server （或任何你喜欢的东西）
3. 支持的帐户类型： “仅限Microsoft个人帐户”
4. 重定向URI: http://localhost:8400/callback （类型： 网络)
5. 创建后，请注意 应用程序（客户端）ID
6. 在...之下 证书和秘密 → 新客户机密 → 注意秘密值（仅显示一次）
7. 在...之下 API权限 → 添加权限 → 微软图形 → 委托权限 --添加：

- Mail.ReadWrite - Mail.Send - MailboxSettings.ReadWrite - Calendars.ReadWrite - Contacts.ReadWrite - Tasks.ReadWrite - User.Read

1. 无需管理员同意——在首次OAuth登录时以交互方式授予同意

______________________________________________________________________

安装

git clone https://github.com/bencan1a/cowork-mcp.git
cd cowork-mcp
python3.11 -m venv venv
. venv/bin/activate
pip install --upgrade pip
pip install -e .

______________________________________________________________________

配置

复制示例env文件并填写您的值：

cp .env.example .env

打开 .env 在文本编辑器中，设置以下内容：

# From your Azure app registration
AZURE_CLIENT_ID=your-client-id-here
AZURE_CLIENT_SECRET=your-client-secret-here

# Path where the encrypted token cache will be stored
TOKEN_CACHE_PATH=/home/ubuntu/outlook-mcp/.token_cache.json

# Encryption key for the token cache — generate with:
# python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
TOKEN_ENCRYPTION_KEY=

# Bearer token for MCP server auth — generate with:
# python -c "import secrets; print(secrets.token_urlsafe(32))"
MCP_API_KEY=

其余设置（范围切换、主机、端口、日志级别）具有合理的默认值。看 .env.example 对于所有选项。

生成秘密值

# TOKEN_ENCRYPTION_KEY
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

# MCP_API_KEY
python -c "import secrets; print(secrets.token_urlsafe(32))"

______________________________________________________________________

初始身份验证

运行一次此操作以使用您的Microsoft个人帐户进行身份验证。浏览器窗口将打开。

. venv/bin/activate
python run_auth.py

该脚本启动了一个临时服务器 http://localhost:8400 自动捕获OAuth重定向。登录并授予同意后，令牌将被加密并保存到 TOKEN_CACHE_PATH.

SOAP在后续运行中自动处理静默令牌刷新。如果刷新令牌过期（在大约90天不活动后），请重新运行 python run_auth.py.

______________________________________________________________________

本地运行（用于测试）

. venv/bin/activate
uvicorn server:app --host 0.0.0.0 --port 8000

测试服务器是否已启动：

# Should return 401 (server is running, auth header missing)
curl -i http://localhost:8000/mcp

# With auth header
curl -i http://localhost:8000/mcp \
  -H "Authorization: Bearer YOUR_MCP_API_KEY"

______________________________________________________________________

在Ubuntu上部署

1.将项目复制到服务器

# On the server
git clone https://github.com/bencan1a/cowork-mcp.git /home/ubuntu/outlook-mcp
cd /home/ubuntu/outlook-mcp
python3.11 -m venv venv
. venv/bin/activate
pip install -e .

2.设置.env文件

复制和配置 .env 在服务器上（与上述步骤相同）。确保 TOKEN_CACHE_PATH 指向服务用户可以写入的绝对路径。

设置安全权限：

chmod 600 /home/ubuntu/outlook-mcp/.env

3.在服务器上运行一次性身份验证流

如果服务器具有桌面环境，或者您可以转发浏览器会话：

python run_auth.py

或者，运行 run_auth.py 在您的本地计算机上使用相同的 .env，然后将令牌缓存文件复制到服务器：

scp .token_cache.json ubuntu@your-server:/home/ubuntu/outlook-mcp/
chmod 600 /home/ubuntu/outlook-mcp/.token_cache.json

4.安装systemd服务

sudo cp deploy/outlook-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable outlook-mcp
sudo systemctl start outlook-mcp

检查状态和日志：

sudo systemctl status outlook-mcp
sudo journalctl -u outlook-mcp -f

______________________________________________________________________

Cloudflare 隧道

看 deploy/cloudflare-tunnel-setup.md 获取分步说明。

简短版本：

# Install cloudflared
curl -L --output cloudflared.deb \
  https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared.deb

# Authenticate and create tunnel
cloudflared tunnel login
cloudflared tunnel create outlook-mcp

# Configure, route DNS, and install as service
# (see full guide for config.yml contents)
sudo cloudflared service install
sudo systemctl enable cloudflared
sudo systemctl start cloudflared

______________________________________________________________________

添加到Claude客户

克劳德代码

claude mcp add --transport http outlook-mcp https://your-tunnel.com/mcp \
  --header "Authorization: Bearer YOUR_MCP_API_KEY"

克劳德桌面

设置→ 开发者→ 编辑配置→ 添加到 mcpServers:

{
  "mcpServers": {
    "outlook-mcp": {
      "type": "http",
      "url": "https://your-tunnel.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_API_KEY"
      }
    }
  }
}

合作/其他克劳德客户

设置→ 连接器（或MCP服务器）→ 添加自定义连接器：

• 网址： https://your-tunnel.com/mcp
• 头球 Authorization: Bearer YOUR_MCP_API_KEY

______________________________________________________________________

可用工具

工具在启动时根据范围切换进行注册 .env。禁用的作用域将被完全跳过。

邮件--阅读(SCOPE_MAIL_READ)

邮件--写(SCOPE_MAIL_WRITE)

邮件--发送(SCOPE_MAIL_SEND)

日历--阅读(SCOPE_CALENDAR_READ)

日历--书写(SCOPE_CALENDAR_WRITE)

联系人--阅读(SCOPE_CONTACTS_READ)

联系人--写(SCOPE_CONTACTS_WRITE，默认关闭）

任务--阅读(SCOPE_TASKS_READ)

任务--编写(SCOPE_TASKS_WRITE，默认关闭）

______________________________________________________________________

故障排除

“AADST50020:租户中不存在来自身份提供程序的用户帐户”

您使用了错误的SOAP。个人Microsoft帐户(@hotmail.com, @outlook.com)要求：

authority="https://login.microsoftonline.com/consumers"

使用 common 或 organizations 个人账户将失败。

令牌过期/刷新失败

重新运行一次性身份验证流：

. venv/bin/activate
python run_auth.py

刷新令牌通常持续90天不活动。经常使用可以使它们无限期地存活。

来自MCP服务器的“401未经授权”

这 Authorization: Bearer 标头缺失或密钥不匹配 MCP_API_KEY 在 .env。验证标头值是否完全匹配。

端口8000已在使用中

sudo lsof -i :8000
# or change PORT in .env and update the systemd service ExecStart line

服务器已启动，但缺少工具

检查相关范围切换是否 true 在 .env 并且服务在更改后重新启动：

sudo systemctl restart outlook-mcp
sudo journalctl -u outlook-mcp -n 50

启动日志行 Registered tool groups: [...] 显示哪些组处于活动状态。

“找不到模块”错误

虚拟环境未激活。确保systemd服务 ExecStart 指向venv Python的完整路径：

ExecStart=/home/ubuntu/outlook-mcp/venv/bin/uvicorn server:app ...

Cloudflare隧道显示“不健康”

检查MCP服务器是否正在端口8000上运行和侦听：

sudo systemctl status outlook-mcp
curl -i http://localhost:8000/mcp

______________________________________________________________________

发展

# Install dev dependencies
pip install -e '.[dev]'
pre-commit install

# Run tests
pytest

# All quality checks
make check-all

# Auto-fix formatting and lint
make fix

看 CLAUDE.md 以获得全面的发展指导。