Minerva MCP — Microsoft 365 & Azure

Minerva MCP

面向 AI 助手的 Microsoft 365 和 Azure 管理——包括 Microsoft Graph 无法触及的部分。

一个 MCP 服务，让 Claude、Copilot、VS Code 或任何 MCP 客户端都能用自然语言查询和管理 Microsoft 365 租户。

---

为什么还要另一个 Microsoft 365 MCP 服务？

已经有一些很不错的服务，本项目并不打算取代它们。

	Lokka	ms-365-mcp-server	Minerva MCP
Microsoft Graph	✅	✅ 300+ 个工具	✅ 通用调用
Azure Resource Manager	✅	—	✅
Exchange Online cmdlet	—	—	✅
SharePoint / PnP cmdlet	—	—	✅
Teams Admin cmdlet	—	—	✅
Purview / 合规性 cmdlet	—	—	✅
每项操作的风险分类	—	—	✅
写入前由人工审批	—	只读开关	✅ 协议原生支持
MCP 2026-07-28（无状态）	—	—	✅

如果你只需要 Graph，请使用 Lokka 或 ms-365-mcp-server。 它们都很出色， 更加成熟，使用也更广泛。尤其是 Lokka，由 Microsoft Entra 产品经理开发。

当你最终遇到人人都会碰到的瓶颈时，可以试试这个服务：Microsoft 365 管理的很大一部分没有 Graph API。 邮箱权限、 传输规则、邮件跟踪、保留策略、敏感度标签、Teams 通话策略、SharePoint 术语库、租户级 Exchange 设置——这些功能 只能通过 PowerShell 使用。本服务提供这些功能，并为所有写入操作设置 风险分类和确认步骤。

---

工作原理

flowchart LR
    A["AI client<br/>Claude · VS Code · Copilot Studio"]
    B["minerva-mcp"]
    C{"Risk<br/>classifier"}
    D["Human<br/>confirmation"]
    G["Microsoft Graph<br/>Azure ARM · Search"]
    P["PowerShell 7<br/>Exchange · PnP · Teams · Purview"]
    M["Microsoft<br/>authorizes the token"]

    A -->|"stdio or HTTP"| B
    B --> C
    C -->|"read"| G
    C -->|"write"| D
    D -->|"signed mandate"| G
    D -->|"signed mandate"| P
    C -->|"read"| P
    G --> M
    P --> M

读取操作会直接执行。写入操作会先经过分类器，然后以描述操作及其后果的 input_required 形式返回给你，并且只有在你确认后才会执行。最终决定权仍在 Microsoft 手中：服务只会转发令牌，绝不会授予访问权限。

安装

无需克隆。将其添加到客户端，然后在首次使用时登录。

Claude Desktop

claude_desktop_config.json：

{
  "mcpServers": {
    "minerva": {
      "command": "npx",
      "args": ["-y", "minerva-mcp", "--stdio"]
    }
  }
}

VS Code

.vscode/mcp.json：

{
  "servers": {
    "minerva": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "minerva-mcp", "--stdio"]
    }
  }
}

更多配置，包括只读和仅应用设置，请参阅 examples/。

首次调用工具时，服务会在 stderr 中显示设备代码提示： 打开链接，输入代码即可。无需注册应用即可试用——默认使用 Microsoft Graph PowerShell 公共客户端。

要求： Node.js 20+。如需使用 PowerShell 工具，还需要 PowerShell 7+ 以及你打算使用的模块（ExchangeOnlineManagement、PnP.PowerShell、 MicrosoftTeams）。

---

你可以询问什么

“哪些邮箱将完全访问权限委派给了部门外的人员？” → 使用 execute_exchange_online 调用 Get-MailboxPermission；Graph 没有对应功能。

“列出所有不要求 MFA 的条件访问策略，并提供我们的安全分数。” → generate_security_report + microsoft_graph_call。

“创建一个用于开票的共享邮箱，并授予财务团队访问权限。” → 该操作会被分类为写入：服务会说明操作及其后果， 并等待你确认后才会执行。

---

工具

工具	功能	是否有 Graph 等效项？
microsoft_graph_call	任意 Microsoft Graph 调用（v1.0 或 beta）	—
azure_arm_call	任意 Azure Resource Manager 调用	—
microsoft_search	统一 Microsoft Search	—
get_tenant_context	组织、许可证、安全分数	—
generate_security_report	租户安全态势	—
execute_exchange_online	Exchange Online cmdlet	❌ 无
execute_pnp_sharepoint	PnP PowerShell（SharePoint）cmdlet	❌ 无
execute_teams_admin	Teams Admin cmdlet	❌ 无
execute_purview_compliance	Purview / 合规性 cmdlet	❌ 无

使用 --tools=microsoft_graph_call,get_tenant_context 限制可用范围，或使用 --read-only 禁止所有写入操作。

---

审批，以及它为何不是可选项

模型会读取不受信任的内容——电子邮件主题、站点名称、文档—— 并决定调用哪个工具。提示词注入并非假设，这里的工具可以删除邮箱。

因此，写入操作不会直接执行。系统会根据 HTTP 方法和路径（或 PowerShell 动词），将每项操作归类为 auto、confirmed 或 critical。凡是高于 auto 的操作，服务都会根据 MCP 的多轮请求返回 input_required： 客户端会显示即将执行的操作及其后果；你确认后，操作才会运行。

确认内容是一份签名授权（HMAC），与调用方、方法和参数摘要绑定，有效期为 5 分钟。为删除 /users/1 获取的授权不能用于重放 /users/999 的操作，也不能由其他人出示。

如果客户端不支持 elicitation，系统不会静默执行任何操作：服务会返回错误，说明该操作需要确认。

---

选项

每个标志都有对应的环境变量。

传输

标志	环境变量	默认值
--stdio	MINERVA_TRANSPORT=stdio	HTTP	通过 stdin/stdout 传输 JSON-RPC
--port=<n>	MCP_SERVER_PORT	3001	HTTP 监听端口

在 stdio 模式下，所有日志都会输出到 stderr——stdout 留给协议使用。

身份验证

标志	环境变量
--auth=<mode>	MINERVA_AUTH_MODE	bearer、device-code、client-secret
--tenant=<id>	MINERVA_TENANT_ID、AZURE_TENANT_ID	Entra 租户
--client-id=<id>	MINERVA_CLIENT_ID、AZURE_CLIENT_ID	应用程序
--client-secret=<s>	AZURE_CLIENT_SECRET	仅应用机密

默认值：HTTP 模式使用 bearer（调用方提供令牌），stdio 模式使用 device-code，存在机密时使用 client-secret。每种资源都有自己的 令牌：Graph、ARM、Exchange、Purview、SharePoint 和 Teams 不共享同一个受众。

范围

标志	环境变量
--read-only	MINERVA_READ_ONLY	拒绝所有写入操作
--tools=<a,b,c>	MINERVA_TOOLS	仅注册这些工具
--ps=<mode>	MINERVA_PS_EXECUTOR	auto、redis、local、none
--sharepoint-url=<url>	MINERVA_SHAREPOINT_URL	本地使用 PnP 工具时必需
--allowed-origins=<a,b>	MINERVA_ALLOWED_ORIGINS	允许访问 /mcp 的浏览器源
--redis-url=<url>	REDIS_URL	外部 PowerShell 运行器的队列
—	MINERVA_MRTR_SECRET	审批授权的签名密钥
—	MINERVA_PWSH_PATH	pwsh 的路径
—	MINERVA_REQUIRE_VERIFIED_TOKENS	拒绝签名无法验证的令牌

--read-only 会复用与审批门禁相同的风险分类器，因此也涵盖 PowerShell cmdlet，而不仅限于 HTTP 方法。

---

协议支持

支持 MCP 2026-07-28，并继续为握手时代的客户端提供服务，直到 2027-07-28。

无状态核心（每个请求的 _meta，无 initialize，无 Mcp-Session-Id）	✅
server/discover	✅
多轮往返请求（input_required）	✅ — 这是审批机制
MCP-Protocol-Version / Mcp-Method / Mcp-Name 标头，base64 哨兵值	✅ 根据请求正文进行验证
列表中的 ttlMs / cacheScope	✅ 始终为 private
版本协商（-32022 列出支持的版本）	✅
Origin 验证（防 DNS 重绑定）	✅
MCP 端点上的 GET/DELETE	✅ 405，此修订版已移除
握手时代（initialize）	✅ 截至 2027-07-28

同一个端点服务于两代客户端；由请求正文决定使用哪一代。两者读取 同一个工具注册表，并通过测试与冻结的契约进行比对，确保不会 出现偏差。

---

安全性

部署前请阅读 SECURITY.md。需要注意的三点：

1. 此服务不授予任何权限。 它会转发 Microsoft 令牌；授权由 Microsoft 负责。受限令牌会使服务受到相同限制。
2. 第三方无法验证 Graph 令牌——其中包含只有 Graph 才能检查的 nonce 标头。因此，其 tid/oid 声明是由令牌自身报告的。服务会在 结构上验证这些声明，将其标记为 verified: false，并将审批授权绑定到 令牌本身的指纹，而不只是声明。如果令牌本应通过验证却未通过， 则会被拒绝。
3. 本地 PowerShell 模式不提供任何隔离。 Cmdlet 以当前用户的权限运行。 不要向不信任的调用方开放此模式。

Cmdlet 名称和参数绝不会作为代码传递给脚本：它们通过环境变量传递，名称会 根据严格的 Verb-Noun 模式进行验证，调用则通过 Get-Command 和调用运算符完成。

请私下报告漏洞——参见 SECURITY.md。

---

本项目不提供的功能

• 本地模式下不提供进程隔离。
• 不提供多租户代理服务——一个服务对应一个身份。
• 不提供签名审计账本。 审计事件以 JSON 格式写入 stderr，不是经签名、 可离线验证的记录。

这三项功能属于 Minerva-IA，即提取此服务的商业 平台。本仓库中的所有内容均可独立运行。

---

开发

npm install
npm run dev:stdio     # stdio, hot reload
npm run verify        # typecheck + tests + secret scan
npm run build && node scripts/smoke-stdio.mjs

测试无需凭据，也不会访问网络。

Pull request 将暂不受理，直至 2027-07-31——原因以及期间欢迎提交的内容 （尤其欢迎 Bug 报告）请参见 CONTRIBUTING.md。

许可证

MIT——参见 LICENSE。