Skip to main content

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.

  1. 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.
  2. In Authentication, under Advanced settings, set Allow public client flows to Yes. This enables the device-code fallback for users without a local browser.

  3. In API permissions → Add a permission → Microsoft Graph → Delegated permissions, add:

    • User.Read
    • Mail.ReadWrite
    • Mail.Send
    • Calendars.ReadWrite
    • Tasks.ReadWrite
    • Only if users should work with shared mailboxes: also Mail.ReadWrite.Shared, Mail.Send.Shared and Calendars.ReadWrite.Shared.

    Then click Grant admin consent for <your organisation>, so users aren't asked to consent individually.

  4. 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
Mail 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 example Inbox/Projects, or /Projects for a top-level folder.
  • Moving: move_email gives the email a new entry_id.
  • Dates: inputs take YYYY-MM-DD, YYYY-MM-DD HH:MM or DD.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 .Shared permissions 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 in claude mcp add ... -e OUTLOOK_GRAPH_SHARED_MAILBOXES=info@contoso.com. If the administrator granted admin consent, the shared permissions are picked up automatically. Otherwise run outlook-graph-mcp-plus auth once 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_id only works with the mailbox it came from. list_mailboxes tells 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.com and graph.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).
  • 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)

Source distribution for outlook-graph-mcp-plus 0.2.0
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)

Table of built distributions (wheels) for outlook-graph-mcp-plus 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page