minerva-mcp

Minerva MCP

Microsoft 365 and Azure administration for AI assistants — including the parts Microsoft Graph cannot reach.

An MCP server that lets Claude, Copilot, VS Code or any MCP client query and administer a Microsoft 365 tenant in plain language.

Why another Microsoft 365 MCP server?

There are already good ones, and this is not trying to replace them.

	Lokka	ms-365-mcp-server	Minerva MCP
Microsoft Graph	✅	✅ 300+ tools	✅ generic call
Azure Resource Manager	✅	—	✅
Exchange Online cmdlets	—	—	✅
SharePoint / PnP cmdlets	—	—	✅
Teams Admin cmdlets	—	—	✅
Purview / compliance cmdlets	—	—	✅
Risk classification per action	—	—	✅
Human approval before writes	—	read-only switch	✅ native to the protocol
MCP 2026-07-28 (stateless)	—	—	✅

If you only need Graph, use Lokka or ms-365-mcp-server. They are excellent, more mature, and more widely used. Lokka in particular is written by a Microsoft Entra product manager.

Reach for this one when you hit the wall everyone hits eventually: a large part of Microsoft 365 administration has no Graph API. Mailbox permissions, transport rules, message trace, retention policies, sensitivity labels, Teams calling policies, SharePoint term stores, tenant-wide Exchange settings — those live in PowerShell and nowhere else. This server exposes them, with a risk classification and a confirmation step in front of anything that writes.

How it fits together

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

Reads go straight through. Writes stop at a classifier, come back to you as an input_required describing the action and its consequences, and only run once you confirm. Microsoft still has the final word: the server forwards a token, it never grants access.

Install

Nothing to clone. Add it to your client and sign in on first use.

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"]
    }
  }
}

More, including read-only and app-only setups, in examples/.

On the first tool call the server prints a device-code prompt on stderr: open the link, enter the code, done. No app registration needed to try it — it uses the public Microsoft Graph PowerShell client by default.

Requirements: Node.js 20+. For the PowerShell tools, PowerShell 7+ and the modules you intend to use (ExchangeOnlineManagement, PnP.PowerShell, MicrosoftTeams).

What you can ask

"Which mailboxes have full access delegated to someone outside their department?" → execute_exchange_online with Get-MailboxPermission, no Graph equivalent exists.

"Show me every conditional access policy that does not require MFA, and our Secure Score." → generate_security_report + microsoft_graph_call.

"Create a shared mailbox for invoicing and give the finance team access." → classified as a write: the server describes the action and its consequences, and waits for your confirmation before doing anything.

Tools

Tool	What it does	Graph equivalent?
microsoft_graph_call	Any Microsoft Graph call (v1.0 or beta)	—
azure_arm_call	Any Azure Resource Manager call	—
microsoft_search	Unified Microsoft Search	—
get_tenant_context	Organisation, licences, Secure Score	—
generate_security_report	Tenant security posture	—
execute_exchange_online	Exchange Online cmdlets	❌ none
execute_pnp_sharepoint	PnP PowerShell (SharePoint) cmdlets	❌ none
execute_teams_admin	Teams Admin cmdlets	❌ none
execute_purview_compliance	Purview / compliance cmdlets	❌ none

Restrict the surface with --tools=microsoft_graph_call,get_tenant_context, or forbid every write with --read-only.

Approval, and why it is not optional

A model reads untrusted content — an email subject, a site name, a document — and decides which tool to call. Prompt injection is not hypothetical, and the tools here can delete mailboxes.

So writes do not simply execute. Every action is classified auto, confirmed or critical from the HTTP verb and path (or the PowerShell verb). Anything above auto makes the server answer input_required under MCP's Multi Round-Trip Requests: your client shows what is about to happen and its consequences, you confirm, and only then does it run.

The confirmation is a signed mandate (HMAC) bound to the caller, the method, and a digest of the arguments, valid five minutes. A mandate obtained to delete /users/1 cannot be replayed on /users/999, and cannot be presented by anyone else.

If your client does not support elicitation, nothing is silently executed: the server returns an error saying the action needs confirmation.

Options

Every flag has an environment variable equivalent.

Transport

Flag	Env	Default
--stdio	MINERVA_TRANSPORT=stdio	HTTP	JSON-RPC over stdin/stdout
--port=<n>	MCP_SERVER_PORT	3001	HTTP listen port

In stdio mode all logs go to stderr — stdout belongs to the protocol.

Authentication

Flag	Env
--auth=<mode>	MINERVA_AUTH_MODE	bearer, device-code, client-secret
--tenant=<id>	MINERVA_TENANT_ID, AZURE_TENANT_ID	Entra tenant
--client-id=<id>	MINERVA_CLIENT_ID, AZURE_CLIENT_ID	Application
--client-secret=<s>	AZURE_CLIENT_SECRET	App-only secret

Defaults: bearer over HTTP (the caller supplies the token), device-code over stdio, client-secret as soon as a secret is present. Each resource gets its own token: Graph, ARM, Exchange, Purview, SharePoint and Teams do not share an audience.

Scope

Flag	Env
--read-only	MINERVA_READ_ONLY	Refuse every write
--tools=<a,b,c>	MINERVA_TOOLS	Register only these tools
--ps=<mode>	MINERVA_PS_EXECUTOR	auto, redis, local, none
--sharepoint-url=<url>	MINERVA_SHAREPOINT_URL	Required by the PnP tool locally
--allowed-origins=<a,b>	MINERVA_ALLOWED_ORIGINS	Browser origins allowed on /mcp
--redis-url=<url>	REDIS_URL	Queue for an external PowerShell runner
—	MINERVA_MRTR_SECRET	Signing key for approval mandates
—	MINERVA_PWSH_PATH	Path to pwsh
—	MINERVA_REQUIRE_VERIFIED_TOKENS	Refuse tokens whose signature cannot be verified

--read-only reuses the same risk classifier as the approval gate, so it covers PowerShell cmdlets too, not just HTTP verbs.

Protocol support

Speaks MCP 2026-07-28, and still serves handshake-era clients until 2027-07-28.

Stateless core (per-request _meta, no initialize, no Mcp-Session-Id)	✅
server/discover	✅
Multi Round-Trip Requests (input_required)	✅ — this is the approval mechanism
MCP-Protocol-Version / Mcp-Method / Mcp-Name headers, base64 sentinel	✅ validated against the body
ttlMs / cacheScope on lists	✅ always private
Version negotiation (-32022 listing supported versions)	✅
Origin validation (anti DNS-rebinding)	✅
GET/DELETE on the MCP endpoint	✅ 405, removed by this revision
Handshake era (initialize)	✅ until 2027-07-28

One endpoint serves both generations; the request body decides which. Both read the same tool registry, and a test compares them against a frozen contract so they cannot drift.

Security

Read SECURITY.md before deploying. The three things that matter:

• This server grants nothing. It forwards a Microsoft token; Microsoft authorizes. A restricted token gives a restricted server.
• Graph tokens cannot be verified by a third party — they carry a nonce header that only Graph can check. Their tid/oid claims are therefore self-reported. The server validates them structurally, flags them verified: false, and binds approval mandates to a fingerprint of the token itself rather than to the claims alone. A token that should have verified and did not is rejected.
• Local PowerShell mode isolates nothing. Cmdlets run with the current user's rights. Do not expose it to a caller you do not trust.

Cmdlet names and parameters never reach the script as code: they travel through environment variables, the name is validated against a strict Verb-Noun pattern, and the call goes through Get-Command plus the call operator.

Report a vulnerability privately — see SECURITY.md.

What this does not do

• No process isolation in local mode.
• No multi-tenant brokering — one server, one identity.
• No signed audit ledger. Audit events are JSON on stderr, not a signed, offline-verifiable record.

Those three belong to Minerva-IA, the commercial platform this server was extracted from. Everything in this repository works without it.

Development

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

Tests need no credentials and touch no network.

Pull requests are closed until 2027-07-31 — see CONTRIBUTING.md for why, and for what is welcome in the meantime (bug reports very much are).

Licence

MIT — see LICENSE.