Variable

Purpose

M365_CLIENT_ID

Microsoft Entra application (client) ID for the registered app.

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.

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>.

M365_TRANSCRIPT_MAX_BYTES

Max raw VTT bytes read from Graph per get_transcript call. Defense-in-depth bound against the audit-S7 whole-file-buffering pattern. Default 10000000 (10 MB ≈ 8 h+ of speech).

M365_TRANSCRIPT_MAX_CHARS

Max parsed-text characters returned in a single get_transcript response. Long transcripts page via the tool's offset + next_offset fields. Default 200000 (~2 h of speech).

Tool

Purpose

Input

Output

Required scope

m365-graph:list_sites

Finds SharePoint sites the user can access (keyword search; * = all). If the keyword search finds nothing (Graph search can miss e.g. hyphenated names), falls back to a case-insensitive substring match on name, display name and URL over all accessible sites. Security-trimmed by SharePoint. Pass a returned id to list_drives.

query? (default *, 1–200 chars), limit? (1–100, default 50)

{ query, match, count, sites: [] } (match: search or name_filter) with id / name / display_name / web_url.

Sites.Read.All (covered by Sites.ReadWrite.All)

m365-graph:list_drives

Without site_id: the user's own OneDrive drives (primary + /me/drives). With site_id: the document libraries of that SharePoint site. SharePoint libraries are only returned with site_id.

site_id? (from list_sites, {hostname},{guid},{guid})

without site_id: { primary, accessible: [], note }; with: { site_id, count, drives: [] }. Drives carry id / driveType / name / webUrl / owner.

Files.Read; Sites.Read.All with site_id

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. With format: "pdf", Microsoft Graph converts the file to PDF server-side (no local converter) and the PDF is saved as <name>.pdf in the same sandbox; unsupported source types are rejected with an error listing the supported ones.

item_id (required), drive_id?, format? (pdf)

{ local_path, size_bytes, name, content_type, format }, where format is "pdf" when converted (content_type is then application/pdf) and null for a plain download; when converted also source_size_bytes, source_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_name / owner_email / 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)

{ calendar_id, window, count, events: [] } with id / subject / body_preview / start / end / is_all_day / is_online_meeting / location / organizer_name / organizer_email / attendees / webLink.

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, online-meeting join URL when applicable.

event_id (required)

event summary + body / body_content_type / body_truncated / recurrence / online_meeting_join_url.

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_folder

Creates a folder in a drive (OneDrive primary by default; SharePoint document library via drive_id). Synchronous POST to /children. Returns the new folder's item ID so it can be passed as parent_item_id to a subsequent upload_file / create_folder call. replace conflict behavior is intentionally not exposed (compose delete_file + create_folder if truly needed).

name (required), parent_item_id?, drive_id?, conflict_behavior? (fail/rename, default fail)

{ created: { id, name, webUrl, parent_id, child_count } }

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. Long transcripts page via offset + next_offset; per-call cap and upstream byte cap configurable via M365_TRANSCRIPT_MAX_CHARS / M365_TRANSCRIPT_MAX_BYTES (defaults 200 000 chars / 10 MB).

meeting_id + transcript_id (required, from list_meeting_transcripts); offset? (0..2_000_000_000), max_chars?

{ meeting_id, transcript_id, offset, char_count, next_offset, total_char_count, truncated, vtt_truncated, transcript }

OnlineMeetingTranscript.Read.All ¹