ms365-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ms365-mcp Create a draft email to Jane about the quarterly report."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ms365-mcp
A Microsoft 365 MCP server sized for small local models.
Most MCP servers are built for frontier models with large context windows, so they expose everything the vendor API offers and let the model sort it out. The reference Microsoft 365 server exposes 326 tools generated from Microsoft's Graph OpenAPI spec.
That does not work for an 8B model at 8k context, where the entire tool list sits in the system prompt and the model starts choosing at random somewhere past twenty-five tools. This server takes the opposite approach:
Fourteen hand-written tools, with a hard ceiling of twenty. The tool list is a budget, not a feature list.
Descriptions written for a small model, not salvaged from API metadata.
Draft-first. Exactly one tool can transmit to another person, it takes a draft id rather than a recipient, and it is annotated destructive.
Every tool declares its own effect through MCP
readOnlyHintanddestructiveHintannotations, so a host can classify it without guessing from the tool's name.
Built for the Edge Harness, and useful to any MCP client.
Status
Feature complete, not yet run against a real account. All fourteen tools are implemented and 171 tests pass, none of which touch the network. What has not happened is the part only a real tenant can prove: a live sign-in and a Graph call that gets answered. See docs/PLAN.md for the ten commits and the reasoning behind each decision.
Scaffold, licence, CI | done |
MCP protocol over stdio | done |
The fourteen-tool surface | done, all fourteen implemented |
Sign-in | done, untested against a live tenant |
Microsoft Graph | done, tested against recorded shapes only |
Retries and circuit breaker | done |
Related MCP server: google-nice-mcp
Seeing the tool surface
--list-tools starts nothing and needs no account, so it answers "what would
a host be offered?" before any of it is wired up:
.venv/bin/python -m ms365_mcp --list-toolsAdd --json for a machine-readable version.
read whoami Return the display name, email address and timezone…
read resolve_person Look up a person by name or partial name and return…
read list_messages List messages in a mail folder, newest first, as se…
write create_draft Create a draft message. This does NOT send anything…
! write send_draft Send a draft that already exists, by its id. This r…
...
14 tools, 6 that change something, 4 marked destructive (!)Handlers are stubs today: a call returns a sentence saying the tool is declared but not implemented. The surface is deliberately fixed before any of it is built, because the tool names, descriptions and effect classes are what a host classifies and a model is prompted against, and those are expensive to change later.
Signing in
Sign-in is the Microsoft device code flow, so there is no redirect URL to host and no secret to store. You need one thing first: the application id of an Azure app registration that has the delegated Graph permissions this server's tools declare.
export MS365_MCP_CLIENT_ID=<your app registration's application id>
export MS365_MCP_TENANT_ID=organizations # 'consumers' for outlook.com
.venv/bin/python -m ms365_mcp --loginThen check it, before wiring anything into a host:
.venv/bin/python -m ms365_mcp --verify-login--verify-login prints the client id, tenant, authority, scopes and cache
location, and if an account is cached it calls Graph once. That last part is
the point. A cached token can look completely healthy and still be refused,
because a work or school tenant can withhold consent for a scope the surface
needs, and that only ever shows up as a 403 on a real request. --logout
forgets the account and removes the cache.
The token cache lives in the operating system's config directory, never in this repository. It is created with mode 0600 rather than written and then made private, since the gap between those two is a window where a refresh token is readable by every account on the machine. It is replaced by an atomic rename, so an interrupted write costs nothing.
Using it from the Edge Harness
The harness launches this server as a subprocess over stdio, so it runs under
its own interpreter and shares no dependencies with the host. That is not
incidental: the harness has a local package called mcp/ and the official SDK
on PyPI is also called mcp, so installing this server into the harness's
virtualenv shadows the harness's own package.
Its registry entry there is ms365-own, and pressing Check in the Agent
Lab run options lists every tool with its effect class. All fourteen classify
as declared, meaning the harness took them from this server's annotations
rather than guessing from tool names, and the entry needs no overrides.
In the harness's default draft mode, send_draft is withheld and the other
thirteen are available, so a run cannot reach a person.
Errors are raised as the SDK's ToolError rather than allowed to propagate.
That is worth knowing if you are writing a handler here: the SDK treats any
other exception as a crash and replaces its message with a generic one, so a
sentence like "No signed-in account, run --login" is discarded before it ever
reaches the model. ToolError is the deliberate-failure channel and its text
survives, while the result is still flagged as an error.
Security
This repository is public and holds no credential of any kind.
Authentication uses the Microsoft device-code flow. The resulting token cache
is written to the operating system's config directory with owner-only
permissions, never into this repository or its working tree. .gitignore
covers token and cache filenames anyway, and a pre-commit hook scans staged
changes for credential-shaped strings, so committing one takes deliberate
effort rather than a slip.
A line ending in # pragma: allowlist secret is skipped by the hook. That
exists so this repository's own tests can contain fake credentials, and it
leaves a marker a reviewer can see in the diff, which --no-verify does not.
Use it only for data that is provably fake.
Development
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest -qEnable the secret-scan hook once per clone:
git config core.hooksPath .githooksLicence
MIT. See LICENSE.
Available Tools
14 toolscancel_eventCancel an eventADestructive
Cancel an event and notify every attendee. This CANNOT be undone. Read the event with get_event first and be sure it is the right one.
Inputs: event_id (required), message.
create_draftDraft a messageA
Create a draft message. This does NOT send anything: it leaves a draft a person can read and change. Get every recipient address from resolve_person first. Returns a draft id, which send_draft takes if the message is later approved.
Inputs: to (required), body (required), subject (required).
create_eventCreate an eventADestructive
Create a calendar event. If it has attendees, they are invited, which reaches real people, so get their addresses from resolve_person and check the slot with find_free_time first.
Inputs: end (required), start (required), subject (required), location, +1 more.
find_free_timeFind a free slotARead-only
Find open slots of a given length on a date, respecting existing events and working hours. Use this instead of reading the calendar and working out the gaps yourself, which is where arithmetic mistakes turn into double bookings.
Inputs: date (required), minutes.
get_eventRead an eventARead-only
Read one calendar event in full, including its body and the response status of each attendee, by the id list_events returned.
Inputs: event_id (required).
get_messageRead a messageARead-only
Read one message in full, including its body, by the id that list_messages returned. Read the message before replying to it or summarising it; a reply written from the subject line alone invents its own content.
Inputs: message_id (required).
list_eventsList calendar eventsARead-only
List calendar events between two dates, with subject, start, end, location, attendees and id. Dates are YYYY-MM-DD in the account's own timezone. Check the calendar before booking anything, so a new event does not land on top of an existing one.
Inputs: end_date (required), start_date (required).
list_foldersList mail foldersARead-only
List the mail folders on this account with their names and message counts. Use it when a task names a folder you have not seen, rather than guessing that it exists.
Inputs: no named parameters.
list_messagesList mailARead-only
List messages in a mail folder, newest first, as sender, subject, date and id. Bodies are not included; use get_message with an id to read one. Defaults to the inbox and to 10 messages.
Inputs: top, folder, search.
reply_draftDraft a replyA
Create a draft reply to an existing message, keeping its thread and recipients. Does NOT send. Read the message with get_message first, so the reply answers what was actually asked.
Inputs: body (required), message_id (required), reply_all.
resolve_personFind someone's addressARead-only
Look up a person by name or partial name and return their real email address. ALWAYS use this before addressing a message or inviting someone. Never type an email address you were not given. If this returns more than one person, ask which one rather than picking.
Inputs: name (required).
send_draftSend a draftADestructive
Send a draft that already exists, by its id. This reaches a real person and CANNOT be undone. There is deliberately no way to write and send in one step: create the draft, check it is right, then send it.
Inputs: draft_id (required).
update_eventChange an eventADestructive
Change the time, subject or location of an existing event. Attendees are notified. Only the fields you pass are changed. Read the event with get_event first, so you are not overwriting something you have not seen.
Inputs: event_id (required), end, start, subject, +1 more.
whoamiWho am IARead-only
Return the display name, email address and timezone of the signed-in account. Call this when the task says 'me', 'my' or 'I' and you need the actual address, rather than guessing it.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct resource and action: identity, people lookup, mail read/draft/send, and calendar read/find/write. The only close pair, create_draft and reply_draft, is clearly separated by new-vs-reply intent.
Almost all tools follow a consistent verb_noun pattern (list_messages, create_draft, cancel_event). The lone exception is whoami, which is a conventional single-word command but breaks the otherwise uniform pattern.
14 tools is a well-scoped size for a mail-plus-calendar server. Each tool covers a necessary step in reading, creating, and sending mail or managing calendar events, with no redundant utilities.
Calendar coverage is complete with list/get/find/create/update/cancel, and mail covers read, draft, reply-draft, and send. Minor gaps such as updating/deleting drafts or searching messages exist, but agents can work around them with the provided tools.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Hosted MCP endpoint with realistic fake data for prototyping agents. 12 tools, no setup.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA production-ready MCP server that provides secure, delegated access to Microsoft 365 services including Email, SharePoint, OneDrive, and Calendar. It enables AI models to search messages, browse files, manage calendar events, and parse document contents using OAuth 2.1 authentication.MIT
- AlicenseAqualityDmaintenanceA read-only MCP server for Gmail and Drive with only 5 tools, designed to be friendly to small local LLMs by minimizing context usage and simplifying inputs.5MIT
- AlicenseBqualityFmaintenanceLightweight MCP server that enables AI agents to manage Microsoft Outlook email, calendar, and files using PKCE authentication with only a Client ID.46MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that exposes a Microsoft 365 mailbox via the Model Context Protocol, enabling AI assistants to search, read, and download emails and attachments, and optionally send mail.-