MCP-微软办公服务器

Name: MCP-微软办公服务器
Author: Aanerud

作者：Aanerud34 星标更新：2025-07-10

安装使用来源：spider==github.com

项目介绍

🚀 MCP Microsoft Office - 企业级 Microsoft 365 集成

最全面、安全且以用户为中心的 MCP 服务器用于 Microsoft 365

通过 Claude 和其他大语言模型（LLMs）以企业级安全性、全面的日志记录以及无缝多用户支持来改变您与 Microsoft 365 的交互方式。

✨ 为什么这个项目特别

🔐 用户中心的安全性：每个用户都有自己的隔离加密数据空间
📊 企业日志记录：具有完全可观测性的四级全面日志系统
🛠️ 50 多种专业工具：完整的 Microsoft 365 API 覆盖并经过验证
⚡ 零配置设置：自动项目初始化 —— 只需 npm install 即可！
🏢 多用户准备就绪：基于会话的隔离并使用 Microsoft 认证
🔧 开发者友好：广泛的调试、监控和错误处理

🚀 快速开始（适合初学者）

1. 一键设置 ⚡

git clone https://github.com/Aanerud/MCP-Microsoft-Office.git
cd MCP-Microsoft-Office
npm install  # ✨ 这会自动完成一切！（我希望如此！）

自动执行的操作：

✅ 创建带有用户隔离的安全数据库
✅ 生成 .env 配置文件
✅ 设置所有必需的目录
✅ 初始化日志记录和监控系统
✅ 准备多用户会话管理

2. 添加您的 Microsoft 365 凭据 🔑

编辑自动生成的 .env 文件：

MICROSOFT_CLIENT_ID=your_client_id_here
MICROSOFT_TENANT_ID=your_tenant_id_here

📋 获取这些凭据的方法： Azure 应用注册门户

3. 启动您的服务器 🎯

npm run dev:web  # 全面开发模式，带全面日志记录

🌐 访问您的服务器： http://localhost:3000

🛠️ 完整工具集

📧 电子邮件管理（9 种工具）

getMail / readMail - 使用过滤器检索收件箱消息
sendMail - 编写并发送带有附件的电子邮件
searchMail - 使用 KQL 查询的强大电子邮件搜索
flagMail - 标记/取消标记重要电子邮件
getEmailDetails - 查看完整的电子邮件内容和元数据
markAsRead / markEmailRead - 更新已读状态
getMailAttachments - 下载电子邮件附件
addMailAttachment - 向电子邮件添加文件
removeMailAttachment - 删除电子邮件附件

📅 日历操作（13 种工具）

getCalendar / getEvents - 使用过滤器查看即将发生的事件
createEvent - 安排带有参会者和会议室的会议
updateEvent - 修改现有日历条目
cancelEvent - 从日历中删除事件
getAvailability - 检查空闲/忙碌时间
acceptEvent - 接受会议邀请
tentativelyAcceptEvent - 暂时接受会议
declineEvent - 拒绝会议邀请
findMeetingTimes - 寻找最佳会议时段
getRooms - 查找可用会议室
getCalendars - 列出所有用户的日历
addAttachment - 向日历事件添加文件
removeAttachment - 删除事件附件

📁 文件管理（11 种工具）

listFiles - 浏览 OneDrive 和 SharePoint 文件
searchFiles - 按名称或内容查找文件
downloadFile - 获取文件内容
uploadFile - 将新文件添加到云存储
getFileMetadata - 查看文件属性和权限
getFileContent - 读取文档内容
setFileContent / updateFileContent - 修改文件内容
createSharingLink - 生成安全共享 URL

🔧 高级配置

环境变量

# Microsoft 365 配置
MICROSOFT_CLIENT_ID=your_client_id
MICROSOFT_TENANT_ID=your_tenant_id

# 服务器配置
PORT=3000
NODE_ENV=development

# 安全
MCP_ENCRYPTION_KEY=your_32_byte_encryption_key
MCP_TOKEN_SECRET=your_jwt_secret

# 数据库（可选，默认为 SQLite）
DATABASE_TYPE=sqlite  # 或 'mysql', 'postgresql'
DATABASE_URL=your_database_url

# 日志记录
LOG_LEVEL=info
LOG_RETENTION_DAYS=30

数据库支持

✅ SQLite（默认 - 零配置）
✅ MySQL（生产就绪）
✅ PostgreSQL（企业级）

备份与迁移

# 备份用户数据
npm run backup

# 从备份恢复
npm run restore backup-file.sql

# 数据库迁移
npm run migrate

💡 实际使用示例

自然语言查询 🗣️

# 电子邮件管理
"显示我上周未读的邮件"
"向项目团队发送会议纪要"
"查找关于 Q4 预算的邮件"

# 日历操作
"明天我有哪些会议？"
"下周二下午 2 点与 Sarah 安排一对一会议"
"找到 John、Mary 和我都在空闲的时间"

# 文件管理
"查找我上个月的 PowerPoint 演示文稿"
"与团队分享项目提案"
"上传最新的预算电子表格"

# 人员与联系人
"查找市场部门的联系人"
"获取 John Smith 的联系信息"
"谁是我最频繁的电子邮件联系人？"

高级 API 使用 🔧

// 带完整验证的直接 API 调用
POST /api/v1/mail/send
{
    "to": ["colleague@company.com"],
    "subject": "项目更新",
    "body": "这是最新的更新...",
    "attachments": [{
        "name": "报告.pdf",
        "contentBytes": "base64_encoded_content"
    }]
}

// 带参会者的日历事件创建
POST /api/v1/calendar/events
{
    "subject": "团队站会",
    "start": "2024-01-15T09:00:00Z",
    "end": "2024-01-115T09:30:00Z",
    "attendees": ["team@company.com"],
    "location": "会议室 A"
}

// 使用高级过滤器的文件搜索
GET /api/v1/files?query=presentation&limit=10&type=powerpoint

🚨 故障排除与支持

常见问题及解决方案

数据库问题 🗄️

# 完全重置数据库
npm run reset-db

# 检查数据库健康状况
curl http://localhost:3000/api/health

# 查看数据库日志
tail -f data/logs/database.log

认证问题 🔐

# 检查 Microsoft 365 配置
echo $MICROSOFT_CLIENT_ID
echo $MICROSOFT_TENANT_ID

# 测试认证端点
curl http://localhost:3000/api/auth/status

# 清除数据
rm -rf data/*

权限错误 📁

# 修复目录权限
chmod -R 755 data/
chown -R $USER:$USER data/

# 检查磁盘空间
df -h

高级调试 🔍

启用全面日志记录

# 完整调试模式
npm run dev:web

# 特定类别日志记录
DEBUG=mail,calendar npm run dev:web

# 查看实时日志
curl http://localhost:3000/api/logs?limit=100&level=debug

性能监控

# 检查系统指标
curl http://localhost:3000/api/health

# 监控 API 响应时间
curl -w "@curl-format.txt" http://localhost:3000/api/mail

# 数据库性能
sqlite3 data/mcp.sqlite ".timer on" "SELECT COUNT(*) FROM user_logs;"

🎯 生产部署

环境设置

# 生产环境变量
NODE_ENV=production
PORT=3000
DATABASE_TYPE=postgresql
DATABASE_URL=postgresql://user:pass@host:5432/mcpdb
MCP_ENCRYPTION_KEY=your_32_byte_production_key
LOG_LEVEL=info
LOG_RETENTION_DAYS=90

加强安全性

# 生成安全加密密钥
openssl rand -hex 32

# 设置正确的文件权限
chmod 600 .env
chmod 700 data/

# 启用 HTTPS（推荐）
HTTPS_ENABLED=true
SSL_CERT_PATH=/path/to/cert.pem
SSL_KEY_PATH=/path/to/key.pem

监控与告警

# 健康检查端点
GET /api/health

# 用户活动监控
GET /api/logs?scope=user&limit=1000

# 系统指标
GET /api/metrics

🏆 什么使这个项目卓越

🔒 企业级安全性

零信任架构：每次请求都经过身份验证和授权
用户数据隔离：用户数据之间完全分离
静态数据加密：所有敏感数据在数据库中加密
会话安全：带有自动清理的安全会话管理
审计跟踪：所有用户活动的完整日志记录

📊 全面可观测性

四级日志：从开发调试到用户活动跟踪
实时监控：实时系统健康和性能指标
错误跟踪：带有完整上下文的结构化错误处理
性能分析：响应时间、成功率和使用模式

🛠️ 开发者体验

零配置：自动设置，只需 npm install
广泛验证：所有 API 端点的 Joi 模式
类型安全：全面的参数验证和转换
错误处理：带有详细诊断的优雅错误处理
开发工具：丰富的调试和监控能力

🏢 生产就绪

多数据库支持：SQLite、MySQL、PostgreSQL
水平扩展：基于会话的架构支持负载均衡
健康检查：全面的健康监控端点
备份与恢复：内置备份和迁移工具
加强安全性：生产就绪的安全配置

📚 API 文档

认证端点

GET  /api/auth/status     # 检查认证状态
POST /api/auth/login      # 启动 Microsoft 365 登录
GET  /api/auth/callback   # OAuth 回调处理器
POST /api/auth/logout     # 登出并清理会话

邮件 API 端点

GET    /api/v1/mail              # 获取收件箱消息
POST   /api/v1/mail/send         # 发送带有附件的电子邮件
GET    /api/v1/mail/search       # 搜索电子邮件
PATCH  /api/v1/mail/:id/flag     # 标记/取消标记电子邮件
GET    /api/v1/mail/:id          # 获取电子邮件详情
PATCH  /api/v1/mail/:id/read     # 标记为已读/未读

日历 API 端点

GET    /api/v1/calendar          # 获取日历事件
POST   /api/v1/calendar/events   # 创建新事件
PUT    /api/v1/calendar/events/:id # 更新事件
DELETE /api/v1/calendar/events/:id # 取消事件
GET    /api/v1/calendar/rooms    # 获取可用房间

文件 API 端点

GET    /api/v1/files             # 列出文件
GET    /api/v1/files/search      # 搜索文件
POST   /api/v1/files/upload      # 上传文件
GET    /api/v1/files/:id         # 获取文件元数据
GET    /api/v1/files/:id/content # 下载文件

人员 API 端点

GET    /api/v1/people            # 获取相关联系人
GET    /api/v1/people/search     # 搜索联系人
GET    /api/v1/people/:id        # 获取联系人详情

系统端点

GET    /api/health               # 系统健康检查
GET    /api/logs                 # 获取系统/用户日志
POST   /api/v1/query             # 自然语言查询

全面审计跟踪

认证事件：登录、登出、令牌刷新活动
授权变更：权限授予和撤销
数据访问：文件访问、电子邮件阅读、日历视图
管理动作：配置更改和系统更新

🛡️ 安全与合规优势

企业安全标准

零信任架构：每次操作都被记录并验证
审计合规性：完整的活动轨迹用于合规报告
事件响应：详细的日志用于安全事件调查
用户问责制：所有操作清晰地归因于经过身份验证的用户

多租户安全性

数据隔离：不同用户账户之间的完全分离
会话安全：带有适当清理的安全会话管理
令牌安全：绑定用户并有有效期的 JWT 令牌
访问日志：所有访问尝试都带有上下文的日志

🔍 日志分类与结构

支持的日志分类

auth - 认证和授权事件
mail - 电子邮件操作和活动
calendar - 日历事件和调度
files - 文件访问和管理
people - 联系人和目录操作
graph - Microsoft Graph API 交互
storage - 数据库和存储操作
request - HTTP 请求/响应日志
monitoring - 系统监控和指标

日志条目结构

{
    "id": "log_entry_uuid",
    "timestamp": "2025-07-06T17:04:23.131Z",
    "level": "info",
    "category": "mail",
    "message": "电子邮件发送成功",
    "context": {
        "userId": "ms365:user@company.com",
        "operation": "sendMail",
        "duration": 1250,
        "recipientCount": 3
    },
    "sessionId": "session_uuid",
    "deviceId": "device_uuid"
}

🚀 生产就绪日志

此日志系统是 生产测试过的 并提供：

高性能：对 API 操作的最小开销
可扩展性：高效存储和检索大量日志
可靠性：强大的错误处理和回退机制
可维护性：明确的关注点分离和结构化数据

日志系统确保对系统操作的完全可见性，同时保持最高的用户隐私和数据安全标准。

多用户架构

远程服务设计

Claude Desktop ←→ MCP Adapter ←→ 远程 MCP 服务器 ←→ Microsoft 365

MCP 服务器可以作为远程服务部署，允许多个用户通过 MCP 适配器连接：

基于会话的用户隔离：用户会话由 session-service.cjs 管理，并具有唯一的会话 ID
双重认证：支持浏览器会话和 JWT 承载令牌认证
远程服务器配置：MCP 适配器通过 MCP_SERVER_URL 环境变量连接
OAuth 2.0 兼容性：支持通过 /.well-known/oauth-protected-resource 端点发现
设备注册：安全管理和授权 MCP 适配器连接

用户隔离与会话管理

每个用户的数据通过基于会话的架构完全隔离：

// 来自 session-service.cjs
async createSession(options = {}) {
    const sessionId = uuid();
    const sessionSecret = crypto.randomBytes(SESSION_SECRET_LENGTH).toString('hex');
    const expiresAt = Date.now() + SESSION_EXPIRY;
    
    const sessionData = {
        session_id: sessionId,
        session_secret: sessionSecret,
        expires_at: expiresAt,
        created_at: Date.now(),
        // 用户特定数据存储
    };
}

🤝 贡献与支持

贡献指南

分叉仓库 并创建一个特性分支
遵循日志模式 —— 所有新代码必须实现四级日志系统
添加全面测试 对于新功能
更新文档 对于任何 API 更改
确保安全性 —— 所有用户数据必须正确隔离

开发设置

# 克隆并设置开发环境
git clone https://github.com/Aanerud/MCP-Microsoft-Office.git
cd MCP-Microsoft-Office
npm install

# 在开发模式下运行，带全面日志
npm run dev:web

# 运行测试
npm test

# 检查代码质量
npm run lint

支持与社区

🐛 错误报告：