outlook-graph-mcp-plus
Microsoft 365 Outlook as a local MCP server for Claude (Desktop and Code): mail, folders, attachments, calendar and Microsoft To Do, through Microsoft Graph.
- Works with Microsoft 365 work and school accounts. Each organisation uses its own app registration in its own Entra ID tenant.
- Delegated sign-in only: each user signs in once and the server can reach only that user's own mailbox, calendar and tasks. There's no client secret and no access to other mailboxes.
- Runs on the user's computer (macOS, Windows, Linux). Outlook doesn't need to be installed. Tokens stay in the operating system's secret store.
- Offers the same 28 tools, with the same names, as its sibling project outlook-desktop-mcp-plus, which controls a locally installed Outlook instead.
Status: alpha (0.2.0). All 28 tools have been tested against a real Microsoft 365 tenant (including sending, to the tester's own address), plus unit tests against a simulated Microsoft Graph. Shared mailboxes are new in 0.2 and were tested live as well.
1. For the Microsoft 365 administrator: app registration
You do this once per organisation, in the Microsoft Entra admin center.
-
Go to Entra ID → App registrations → New registration.
- Name: for example
Claude Outlook (MCP). - Supported account types: Accounts in this organizational directory only (single tenant).
- Redirect URI: platform Public client/native (mobile & desktop), value
http://localhost. - Click Register.
- Name: for example
-
In Authentication, under Advanced settings, set Allow public client flows to Yes. This enables the device-code fallback for users without a local browser.
-
In API permissions → Add a permission → Microsoft Graph → Delegated permissions, add:
User.ReadMail.ReadWriteMail.SendCalendars.ReadWriteTasks.ReadWrite- Only if users should work with shared mailboxes: also
Mail.ReadWrite.Shared,Mail.Send.SharedandCalendars.ReadWrite.Shared.
Then click Grant admin consent for <your organisation>, so users aren't asked to consent individually.
-
Note the Application (client) ID and the Directory (tenant) ID from the Overview page and give both to your users. They aren't secret.
No client secret or certificate is needed.
Optional hardening
- Limit who can use it: in Enterprise applications → (the app) → Properties, set Assignment required to Yes, then assign the users or groups who may use it.
- Conditional Access applies to the browser sign-in (MFA, compliant device, and so on). If your policies block the device code flow, users simply sign in with the browser.
- Revoking access: remove the user's assignment or delete the app registration. Existing refresh tokens stop working.
2. For each user: install, sign in, connect Claude
Install (Python 3.12+ via uv):
uv tool install outlook-graph-mcp-plus
Until the first PyPI release, install from GitHub:
uv tool install git+https://github.com/lord-helicon/outlook-graph-mcp-plus
Sign in once. Use the two IDs from your administrator. A browser window opens for the normal Microsoft sign-in:
OUTLOOK_GRAPH_CLIENT_ID=<application-client-id> OUTLOOK_GRAPH_TENANT_ID=<tenant-id> outlook-graph-mcp-plus auth
On a machine without a browser, add --device-code. You then open a URL on any device and enter the code it shows. outlook-graph-mcp-plus status shows who is signed in, and outlook-graph-mcp-plus logout removes the cached tokens. On Windows PowerShell, set the variables first with $env:OUTLOOK_GRAPH_CLIENT_ID="...".
Connect Claude Code:
claude mcp add outlook-graph -e OUTLOOK_GRAPH_CLIENT_ID=<application-client-id> -e OUTLOOK_GRAPH_TENANT_ID=<tenant-id> -- outlook-graph-mcp-plus
Connect Claude Desktop (Settings → Developer → Edit Config, claude_desktop_config.json):
{
"mcpServers": {
"outlook-graph": {
"command": "outlook-graph-mcp-plus",
"env": {
"OUTLOOK_GRAPH_CLIENT_ID": "<application-client-id>",
"OUTLOOK_GRAPH_TENANT_ID": "<tenant-id>"
}
}
}
}
If Claude can't find the command, use the full path shown by which outlook-graph-mcp-plus (macOS and Linux) or where outlook-graph-mcp-plus (Windows). Restart Claude afterwards.
Configuration
| Variable | Required | Meaning |
|---|---|---|
OUTLOOK_GRAPH_CLIENT_ID |
yes | Application (client) ID of the organisation's app registration |
OUTLOOK_GRAPH_TENANT_ID |
yes | Directory (tenant) ID or domain, for example contoso.onmicrosoft.com. Personal accounts (common, consumers) are refused |
OUTLOOK_GRAPH_ATTACHMENT_DIR |
no | The only folder attachments are saved into (default ~/Downloads) |
OUTLOOK_GRAPH_TIMEZONE |
no | IANA timezone for dates (default: the computer's timezone) |
OUTLOOK_GRAPH_CACHE_DIR |
no | Where the sign-in state is kept (default ~/.outlook-graph-mcp-plus) |
OUTLOOK_GRAPH_SHARED_MAILBOXES |
no | Shared mailboxes this user may work with, for example info@contoso.com,support@contoso.com. Only these are accepted as mailbox |
OUTLOOK_GRAPH_ALLOW_PLAINTEXT_TOKEN_CACHE |
no | true only if no OS secret store exists (for example a Linux box without libsecret) |
Tools
| Area | Tools |
|---|---|
| Mailboxes | list_mailboxes |
list_emails, read_email, search_emails, send_email, reply_email, mark_as_read, mark_as_unread, move_email, list_folders |
|
| Drafts | save_draft, list_drafts, read_draft, send_draft, create_draft_reply |
| Attachments | list_attachments, save_attachment |
| Calendar | list_events, search_events, get_event, create_event, create_meeting, update_event, delete_event |
| Tasks (Microsoft To Do, default list) | list_tasks, get_task, create_task, complete_task, delete_task |
Notes on the tools:
- Folders: standard names work in any Outlook language:
inbox,sent,drafts,deleted,junk,archive,outbox. Custom folders are given by name. If a name exists more than once, give the path, for exampleInbox/Projects, or/Projectsfor a top-level folder. - Moving:
move_emailgives the email a newentry_id. - Dates: inputs take
YYYY-MM-DD,YYYY-MM-DD HH:MMorDD.MM.YYYY [HH:MM]. Outputs are ISO 8601 in your timezone.
Shared mailboxes
Mail and calendar tools take an optional mailbox parameter, for example list_emails(mailbox="info@contoso.com"). Empty means the user's own mailbox. Here's what it needs and how it behaves:
- Admin: the three
.Sharedpermissions above, with admin consent. - Exchange: the user needs Full Access to the shared mailbox. Sending from it also needs Send As. Microsoft refuses anything the user isn't allowed to do.
- Configuration: list the mailbox in
OUTLOOK_GRAPH_SHARED_MAILBOXES, for example inclaude mcp add ... -e OUTLOOK_GRAPH_SHARED_MAILBOXES=info@contoso.com. If the administrator granted admin consent, the shared permissions are picked up automatically. Otherwise runoutlook-graph-mcp-plus authonce more. Use the mailbox's primary email address as shown in the Exchange admin center. Microsoft Graph can't list which mailboxes a user may open, so they must be named. The list also stops text in an email from steering the model into another mailbox. - Ids: an
entry_idonly works with the mailbox it came from.list_mailboxestells the model which mailboxes exist. - Tasks: Microsoft To Do doesn't support shared mailboxes, so the task tools always use the user's own.
Security
- Delegated access: no application permissions and no secrets. The server acts only as the signed-in user, within the permissions the administrator granted.
- Tokens: kept in the macOS Keychain, Windows DPAPI or Linux libsecret. A plaintext cache is only used when explicitly allowed.
- Network: the server only contacts
login.microsoftonline.comandgraph.microsoft.com. There's no telemetry. - Attachments: only ever saved inside the attachment folder:
- The path is resolved before checking, so symlinks and
..can't escape it. - Network and device paths are refused before they're touched.
- Sender-chosen file names are cleaned, and existing files are never overwritten.
- Saved files are marked as downloaded from the internet (Windows Mark-of-the-Web, macOS quarantine).
- The path is resolved before checking, so symlinks and
- Ids from mailbox content are validated and URL-encoded, so they can't redirect a request to another Graph endpoint.
- Third-party content: email subjects, bodies and attachment names come from outside your organisation. A model can be steered by text in an email ("prompt injection"). The server tells the model to treat such content as data and to confirm before sending, replying, moving or deleting. Keep those confirmations switched on in your Claude client.
Development
uv sync --group dev
uv run pytest -q
uv run ruff check src tests && uv run black --check src tests
License
MIT, © 2026 Alexander Rolli.
Metadata
Release files for outlook-graph-mcp-plus 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| outlook_graph_mcp_plus-0.2.0.tar.gz | 97.6 kB | With provenance | Details for outlook_graph_mcp_plus-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| outlook_graph_mcp_plus-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for outlook_graph_mcp_plus-0.2.0-py3-none-any.whl |
Total release size: 128.6 kB
Release files / outlook_graph_mcp_plus-0.2.0.tar.gz
| Download URL | outlook_graph_mcp_plus-0.2.0.tar.gz |
|---|---|
| Size | 97.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bbd5029aa190f7b783fdaacbcc9127e0352d0807a3d87724734cc854e0aa58ae
|
|
BLAKE2b-256 checksum How to use checksums |
38c2dfd7cb394e6a18cc34efab72402e711c8a92d0d3c49a2174c61b5ea9dd34
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / outlook_graph_mcp_plus-0.2.0-py3-none-any.whl
| Download URL | outlook_graph_mcp_plus-0.2.0-py3-none-any.whl |
|---|---|
| Size | 31.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
efd169817a08ddc89ca2eef46501f3089c3944d1b36b4339b1260834710f180b
|
|
BLAKE2b-256 checksum How to use checksums |
a6d94d7efdb97b2ffbc5aeeb7e648e8c8b2e3ff2c0e8c8d46adbd6030f1c3639
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for outlook-graph-mcp-plus 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for outlook_graph_mcp_plus-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.