Msgraph MCP (msgraph-mcp)

msgraph mcp

A主办 模型上下文协议（MCP） 包装Microsoft Graph API的服务器，使人工智能助手能够安全访问Microsoft 365消费者服务（Outlook.com、OneDrive、Microsoft to Do等）。

为什么

MCP允许AI模型通过标准协议调用外部工具。该项目将Microsoft Graph端点公开为MCP工具，因此任何兼容MCP的客户端都可以读取和管理用户的邮件、日历、文件、任务等，而无需直接了解Graph API。

关键设计目标

• 以消费者为中心 --目标是Microsoft个人帐户（MSA），而不是Entra ID/工作帐户。
• 可托管 --作为部署到Azure应用服务的独立服务（FastMCP+Gunicorn/Uvicorn）运行。
• 缺省安全 --使用OAuth 2.0授权码流和PKCE；令牌永远不会暴露给AI客户端。
• 薄包装纸 -以最小的转换将MCP工具调用映射到Graph REST调用，随着Graph API的发展，使服务器易于维护。

快速启动

# Install dependencies
uv sync

# Run the server locally
uv run python -m msgraph_mcp.server

# Run tests
uv run pytest

MCP工具

回声

• echo(message) --回显一条消息（健康检查/烟雾测试）。

微软要做

所有待办事项工具都要求用户通过OAuth进行身份验证。

• list_task_lists() --列出所有带有ID和显示名称的Microsoft待办事项列表。
• list_tasks(list_id) --在任务列表中列出所有任务，显示标题、状态、重要性、截止日期和正文。
• create_task(title, list_id?, due_date?, body?) --创建新任务。在以下情况下使用默认列表 list_id 省略。 due_date 必须在 YYYY-MM-DD 格式。
• update_task(list_id, task_id, title?, status?, due_date?, body?, importance?) --更新任务上的一个或多个字段。有效状态： notStarted, completed.有效重要性： low, normal, high.
• delete_task(list_id, task_id) --从任务列表中删除任务。

电子邮件

所有电子邮件工具都要求用户通过OAuth进行身份验证。

• list_messages(folder_id?, count?) --列出最近的电子邮件，包括发件人、主题、日期、阅读状态和正文预览。可选择按文件夹ID进行筛选。默认计数为10。
• read_message(message_id) --阅读一封包含完整详细信息的特定电子邮件：发件人、收件人、抄送人、日期、重要性、阅读状态和完整正文。
• search_messages(query, count?) --使用Microsoft Graph按关键字搜索电子邮件 $search。返回带有预览的匹配消息。默认计数为10。
• send_message(to, subject, body, cc?) --发送一封电子邮件。 to 和 cc 接受逗号分隔的地址。发送前验证电子邮件格式。
• list_mail_folders() --列出所有邮件文件夹，包括显示名称、邮件计数和未读计数。

日历

所有日历工具都要求用户通过OAuth进行身份验证。

• list_calendars() --列出所有带有名称、颜色、默认指示器和ID的日历。
• list_events(start_date?, end_date?, count?, timezone?) --列出日历事件。当两者都 start_date 和 end_date 按日期范围过滤并展开重复事件。默认计数为10，默认时区为UTC。
• get_event(event_id) --获取日历事件的完整详细信息：主题、时间、地点、组织者、具有响应状态的与会者、正文、重复和在线会议链接。
• create_event(subject, start_time, end_time, timezone?, location?, body?, attendees?, is_all_day?, is_online_meeting?) --创建新的日历事件。 attendees 接受逗号分隔的电子邮件地址。验证时间排序。
• update_event(event_id, subject?, start_time?, end_time?, timezone?, location?, body?, attendees?, is_online_meeting?) --更新日历事件上的一个或多个字段。必须至少提供一个字段。
• delete_event(event_id) --删除日历事件。
• get_availability(start_time, end_time, timezone?, check_only?) --查看忙/闲可用性。默认情况下返回时隙细分，或在以下情况下返回简单的忙/闲答案 check_only=True.

示例用法

> List my task lists
→ calls list_task_lists()

> Show tasks in list AAMkAD...
→ calls list_tasks(list_id="AAMkAD...")

> Create a task "Buy groceries" due 2025-01-20
→ calls create_task(title="Buy groceries", due_date="2025-01-20")

> Mark task AAkBT... in list AAMkAD... as completed
→ calls update_task(list_id="AAMkAD...", task_id="AAkBT...", status="completed")

> Delete task AAkBT... from list AAMkAD...
→ calls delete_task(list_id="AAMkAD...", task_id="AAkBT...")

> List my recent emails
→ calls list_messages()

> Show emails in folder AAMkAD...
→ calls list_messages(folder_id="AAMkAD...")

> Read email AAMkAG...
→ calls read_message(message_id="AAMkAG...")

> Search emails for "budget report"
→ calls search_messages(query="budget report")

> Send an email to john@example.com about the meeting
→ calls send_message(to="john@example.com", subject="Meeting", body="...")

> List my mail folders
→ calls list_mail_folders()

项目结构

msgraph_mcp/
  __init__.py   # Package metadata
  server.py     # MCP server (FastMCP + streamable HTTP + OAuth + To-Do + Email + Calendar tools)
  config.py     # Allowed users and OAuth configuration
  auth.py       # MicrosoftOAuthProvider (MCP OAuth ↔ Microsoft OAuth bridge)
  graph.py      # GraphClient — async Microsoft Graph API wrapper for To-Do, Email, and Calendar
  store.py      # Persistent credential cache (tokens, clients, MSAL cache)
tests/
  conftest.py     # Shared test fixtures
  test_config.py  # Config tests
  test_auth.py    # OAuth provider tests
  test_store.py   # Credential store tests
  test_graph.py   # GraphClient unit tests
  test_tools.py   # To-Do, Email, and Calendar MCP tool tests
infra/
  main.bicep    # Azure App Service infrastructure
.github/
  workflows/deploy.yml  # CI/CD pipeline

认证

服务器使用MCP原生OAuth对Microsoft个人帐户的用户进行身份验证。

先决条件

1. 在以下网址注册应用程序 Azure门户:

- 帐户类型：“仅限Microsoft个人帐户” - 平台：Web - 重定向URI: http://localhost:8000/auth/microsoft/callback - 添加Graph委托权限： User.Read, Mail.ReadWrite, Mail.Send, Calendars.ReadWrite, Tasks.ReadWrite, Files.Read

1. 设置环境变量：

   export MSGRAPH_CLIENT_ID="your-client-id"
   export MSGRAPH_CLIENT_SECRET="your-client-secret"

1. Copilot CLI通过以下方式自动发现身份验证 /.well-known/oauth-protected-resource --不需要特殊的配置。

凭证持久性

服务器将MCP令牌、客户端注册和WAVEtoken缓存保存到磁盘，这样用户在服务器重启后就不需要重新进行身份验证。

存储的文件：

• credentials.json --MCP注册的客户端、访问令牌和刷新令牌。
• msal_cache.json --Microsoft身份平台令牌缓存。

这两个文件都是以原子方式写入的，并且具有限制权限(0o600).加载时，过期的令牌会自动过滤掉。

部署

服务器通过GitHub推送操作部署到Azure应用服务 main.

• 基础设施：二头肌模板 infra/main.bicep
• 实时端点: https://msgraph-mcp.azurewebsites.net/mcp

许可证

待定