M365 Graph Server

@juvantlabs/m365-graph-mcp-server — Model Context Protocol server wrapping the Microsoft Graph API for OneDrive, SharePoint, and Calendar (read + write). Designed to be consumed by Juvant OS agents (or any MCP-aware client) via npx.

Fulfills the m365-graph role per docs/adr/0002-mcp-abstract-roles.md in the handbook (concrete-only — Microsoft Graph is the single provider). The scope of this server (files + calendar; no mail send, no Teams chat) follows the threat-model boundary rule in docs/adr/0003-mcp-server-scope-boundaries.md: mail and Teams chat have materially different blast radius and would ship as separate <vendor>-<capability>-mcp-server packages if a real Juvant OS need surfaces; outbound Teams notifications go through webhooks (Adaptive Cards), not MCP. Per-company instance config binds this server in .juvant/config.json.

What's new in v0.2.0

Teams meeting transcript support. Two new read-only tools:

• m365-graph:list_meeting_transcripts — given a calendar event ID, lists available post-meeting transcripts. Returns transcript IDs to pass to get_transcript.
• m365-graph:get_transcript — fetches the transcript content, strips VTT timing markers, and returns clean readable text (capped at 30 000 chars).

Two new delegated scopes required (admin consent — see § Tools): OnlineMeetings.Read and OnlineMeetingTranscript.Read.All. Re-run npm run setup after upgrading to acquire them.

See CHANGELOG.md for the full change list.

Status

Published. v0.2.0 on npm (@juvantlabs/m365-graph-mcp-server). 19 tools across files (OneDrive + SharePoint), Outlook Calendar, and Teams meeting transcripts. Published via npm Trusted Publishing (OIDC-based auth from GitHub Actions; no static NPM_TOKEN) with provenance attestation; manual approval gate on the production GitHub Environment guards the publish step.

Originally generated by juvantlabs/juvant-tools scaffold mcp-server on 2026-05-03, conforming to the mcp-server.md spec. See CHANGELOG.md for the per-version history.

Install + run

# One-time OAuth (opens browser, persists tokens in OS keychain):
npx @juvantlabs/m365-graph-mcp-server setup

# Run the MCP server on stdio (default subcommand):
npx @juvantlabs/m365-graph-mcp-server

Requires Node ≥ 20. Both invocations expect the env vars below (typically loaded from .env.local via --env-file, or set by your MCP client when it spawns the server).

Environment variables

Required:

Variable	Purpose
M365_CLIENT_ID	Microsoft Entra application (client) ID for the registered app.
M365_CLIENT_SECRET	Client secret for the registered app. Stored only in the consumer's environment; never in .juvant/config.json.
M365_TENANT_ID	Microsoft Entra tenant ID (UUID). The canonical adoption pattern is single-tenant — see ARCHITECTURE.md § Tenancy model. The regex also accepts common / organizations / consumers for technical compatibility with Microsoft authority strings, but multi-tenant operation is not the supported deployment shape.

Optional:

Variable	Purpose
MCP_SERVER_LOG_LEVEL	Log level for diagnostics on stderr (default info).
M365_DOWNLOAD_DIR	Override the per-tenant sandbox directory used by download_file. Default: $XDG_CACHE_HOME/m365-graph-mcp-server/<tenant-id> or ~/.cache/m365-graph-mcp-server/<tenant-id>.

CI enforces that every variable documented in this section is actually read from process.env.<NAME> somewhere in src/ — placeholder names containing <> are skipped. Documenting an env var without wiring it up will fail the build (handbook anti-pattern S2).

OAuth scope minimization is per-tool; see the tool catalog and ARCHITECTURE.md for the per-tool scope justifications.

Binding

The Juvant OS adopter binds this server in .juvant/config.json:

{
  "m365-graph": {
    "provider": "microsoft",
    "mcp_server": "npx @juvantlabs/[email protected]",
    "scope": "rw"
  }
}

Pinning the version in mcp_server keeps installs reproducible. The canonical inventory entry, with the same pin, is at juvant-os/docs/MCP_INVENTORY.md — refer to it for the matrix-side bindings (which agents have m365-graph:rw granted by default in the v0 seed) and the wizard Step 8.5 cross-check semantics.

Tools

Tool	Purpose	Input	Output	Required scope
m365-graph:list_drives	Lists the drives the user has access to (primary OneDrive + shared document libraries).	(none)	{ primary, accessible: [] } with id / driveType / name / webUrl / owner.	Files.Read
m365-graph:list_items	Lists immediate children (files + folders) of a folder. Defaults to the drive root.	drive_id?, item_id?, limit? (1–100, default 50)	{ count, items: [] } with id / name / type / size / child_count / lastModified / webUrl.	Files.Read
m365-graph:search_files	Searches files by name and content within a drive.	query (required), drive_id?, limit? (1–50, default 20)	{ count, results: [] } with id / name / path / size / is_folder / lastModified / webUrl.	Files.Read
m365-graph:download_file	Downloads a file to a per-tenant local sandbox. Returns the local path; agent reads via a filesystem-aware tool. Streams, capped at 200 MB.	item_id (required), drive_id?	{ local_path, size_bytes, name, content_type }	Files.Read
m365-graph:list_calendars	Lists the user's calendars (primary + group / shared).	limit? (1–100, default 50)	{ count, calendars: [] } with id / name / color / owner / is_default / can_edit / can_share.	Calendars.Read
m365-graph:list_events	Lists events in a date window. Recurrences are expanded — each occurrence is its own event.	start + end (ISO 8601, required), calendar_id?, limit? (1–200, default 100)	{ window, count, events: [] } with id / subject / start / end / location / organizer / attendees / web_url.	Calendars.Read
m365-graph:search_events	Searches events by subject substring (Graph $search isn't supported on Events; subject-only via contains()). Returns recurrence series masters, not occurrences.	query (required), limit? (1–50, default 20)	{ count, results: [] } (same event shape).	Calendars.Read
m365-graph:get_event	Fetches full details for a single event — body (capped at 8000 chars), attendees with response statuses, location, recurrence rule.	event_id (required)	event summary + body / body_content_type / body_truncated / recurrence.	Calendars.Read
m365-graph:upload_file	Uploads a local file to a drive. Auto-routes between single PUT (≤ 4 MB) and resumable upload session (> 4 MB, 10 MB chunks). 200 MB hard cap.	local_path (required), drive_id?, parent_item_id?, name?, conflict_behavior? (fail/replace/rename, default fail)	{ uploaded: { id, name, size, webUrl, upload_path } }	Files.ReadWrite
m365-graph:create_event	Creates a new event on the user's primary calendar (or a specified calendar). Sends invitations to attendees by Graph default.	subject + start + end (required), timezone? (default UTC), body?, body_content_type? (text/html), location?, attendees?, is_all_day?, calendar_id?	{ created: <event summary> }	Calendars.ReadWrite
m365-graph:update_event	Updates an existing event. All fields except event_id are optional; only provided fields are PATCHed. Attendees: full replacement, not merge — pass the full intended list.	event_id (required), then any subset of subject/start+end+timezone/body+body_content_type/location/attendees/is_all_day	{ updated: <event summary> }	Calendars.ReadWrite
m365-graph:copy_file	Async copy with polling. POSTs to /items/{id}/copy, polls the monitor URL with exponential backoff (1s → 2s → … capped at 30s) until completion. Falls back to list-by-name if the monitor's completed response omits resourceLocation (common Graph quirk).	item_id + target_parent_id (required); source_drive_id?, target_drive_id?, new_name?, wait_max_seconds? (1–1800, default 300)	{ status: "completed", copied: { id, name, ... } }	Files.ReadWrite
m365-graph:move_file	Synchronous move within a drive (PATCH parentReference). Cross-drive moves are not supported here — use copy_file + delete_file for those.	item_id + target_parent_id (required); drive_id?, new_name?	{ moved: { id, name, ... } }	Files.ReadWrite
m365-graph:delete_file	Two-phase spec/approval: 1st call returns preview + confirmation_token; 2nd call (same args + token) executes the DELETE. Token single-use, 5 min expiry, tied to exact spec (canonical-JSON SHA-256).	item_id (required), drive_id?, confirmation_token?	preview { item, confirmation_token, expires_at } or execute { deleted: { ... } }	Files.ReadWrite
m365-graph:cancel_event	Two-phase like delete_file. Cancels a meeting the user organizes (sends cancellation notice to attendees).	event_id (required), comment?, confirmation_token?	preview or { cancelled: { event_id } }	Calendars.ReadWrite
m365-graph:decline_event	Two-phase. Declines an event the user is invited to (as attendee — distinct from cancel which is for events the user organizes). Sends a decline RSVP unless send_response: false.	event_id (required), comment?, send_response? (default true), confirmation_token?	preview or { declined: { event_id, send_response } }	Calendars.ReadWrite
m365-graph:search_events_content	Subject + body content search via the Microsoft Search API (POST /search/query). Distinct from search_events (subject-only via $filter). Returns recurrence series masters; for occurrences in a window use list_events.	query (required), limit? (1–50, default 25), from? (pagination offset, default 0)	{ count, total, results: [<event summary>] }	Calendars.Read
m365-graph:list_meeting_transcripts	List available transcripts for a Teams meeting identified by its calendar event ID. Transcripts are post-meeting only and require recording to have been enabled by the organizer.	event_id (required)	{ event_id, meeting_id, count, transcripts: [{ id, meeting_id, created_at, end_at }] }	Calendars.Read, OnlineMeetings.Read ¹, OnlineMeetingTranscript.Read.All ¹
m365-graph:get_transcript	Fetch the text content of a Teams meeting transcript. VTT timing markers are stripped; returns clean readable text capped at 30 000 chars.	meeting_id + transcript_id (both required, from list_meeting_transcripts)	{ meeting_id, transcript_id, char_count, truncated, transcript }	OnlineMeetingTranscript.Read.All ¹

¹ Admin consent required. OnlineMeetings.Read and OnlineMeetingTranscript.Read.All must be granted in the Entra app registration under API permissions → Add a permission → Microsoft Graph → Delegated → Grant admin consent. Without admin consent these tools return 403 Forbidden.

That's 4 read + 4 write on files, 5 read + 4 write on calendars, 2 read on meeting transcripts — 19 tools total. Read tools exercise delegated Files.Read + Calendars.Read; write tools require Files.ReadWrite + Calendars.ReadWrite; transcript tools require OnlineMeetings.Read + OnlineMeetingTranscript.Read.All (all separately granted + admin-consented in the Entra app).

Local development

The repo expects a .env.local file with your tenant's credentials. Bootstrap from the template:

cp .env.example .env.local
# then edit .env.local with your M365_TENANT_ID, M365_CLIENT_ID,
# and M365_CLIENT_SECRET — see ARCHITECTURE.md § Authentication
# for the Entra app registration flow.

.env.local is gitignored.

One-time OAuth setup

The first time you run the server, you need to complete an OAuth flow to populate the OS keychain with refresh tokens:

npm run setup

This opens your browser, signs you in to your tenant, captures the authorization code via a one-shot listener at http://localhost:3000/auth/callback, and persists the resulting tokens via @napi-rs/keyring (macOS Keychain / Linux Secret Service / Windows Credential Manager). After that, the server uses cached tokens silently — refreshes as needed via the cached refresh grant.

Run the MCP server

npm run dev

Listens on stdio. Useful when developing alongside an MCP client like Claude Code: configure the client to spawn npm run dev (or tsx --env-file=.env.local src/index.ts) as its MCP server command.

Architecture

See ARCHITECTURE.md for design rationale: scope, OAuth model with @azure/msal-node, token persistence via @napi-rs/keyring, per-tool scope minimization, filesystem sandboxing for upload/download tools, and async-op polling for copy / move.

Contributing

See CONTRIBUTING.md. The repo follows the juvantlabs/handbook conventions for MCP server repos.

Security

See SECURITY.md for the disclosure process. Per the handbook security disclosure process, report vulnerabilities privately via GitHub Security Advisory or [email protected].

License

MIT. Copyright (c) 2026 Juvant Srls.