iris

A Microsoft 365 mail server for AI agents that reads your mailbox and writes drafts, but does not send email — until you decide it should.

By default iris requests the delegated Graph scope Mail.ReadWrite and never Mail.Send. The access token it holds has no capability to transmit a message, so no prompt, no jailbreak and no bug in this code can make one go out. It writes drafts into a folder in your mailbox; you open Outlook and press Send.

Sending is an explicit opt-in (IRIS_ENABLE_SEND=1) that requires granting the Mail.Send scope and re-consenting — and even then every send is human-confirmed and allowlist-checked. Leave it off (the default) and the no-send property is structural, as above. See Enabling send.

That is the whole design. Everything else is detail.

Why this shape

The usual worry about giving an agent your mailbox is that it will send something you did not sanction — to the wrong person, with the wrong tone, or because someone talked it into doing so. The common answer is a confirmation prompt, which is a guardrail: code that asks permission, and code can be bypassed.

iris removes the capability instead. Microsoft Graph will reject a send attempt made with this token, because the consent screen you approved never included that permission. The security boundary is Microsoft's, not this program's, and it holds even if this program is wrong.

The trade is real: a human is in the loop on every message, by construction. If you want autonomous sending, iris is the wrong tool.

Install

uvx iris-mcp        # run without installing
pip install iris-mcp

Python 3.10 or newer. macOS ships Python 3.9, which is too old — mcp requires 3.10+. Use uv (it comes with uvx and manages its own Python), or install a current Python with Homebrew (brew install python@3.12). The system python3 on macOS will not work.

Setup

You must register your own Entra application. There is no shared app registration and no hosted service — iris talks directly from your machine to your tenant. This is deliberate: a shared app would mean trusting someone else's client ID with access to your mail.

1. Entra admin centre → App registrations → New registration. Single tenant is fine. No redirect URI needed.
2. Authentication → Settings → enable Allow public client flows. Device code sign-in needs this. No client secret is used anywhere.
3. API permissions → Microsoft Graph → Delegated → add Mail.ReadWrite. For draft-only use (the default), add nothing else and leave Mail.Send off — that omission is what makes the no-send property structural. Add Mail.Send only if you intend to enable sending (see Enabling send).
4. Copy the Application (client) ID and Directory (tenant) ID. Neither is a secret.

Then add iris to your MCP client:

{
  "mcpServers": {
    "iris": {
      "command": "uvx",
      "args": ["iris-mcp"],
      "env": {
        "IRIS_CLIENT_ID": "<application (client) id>",
        "IRIS_TENANT_ID": "<directory (tenant) id>"
      }
    }
  }
}

Sign in once: call iris_login, open the URL, enter the code, then call iris_login_finish. The token cache is written next to the server, mode 600.

Deploying to a whole team? See the Administrator Deployment Guide — authorizing iris across a Microsoft 365 tenant: admin consent, per-user assignment, and why it stays the delegated model rather than application permissions.

Clients

iris is a local stdio MCP server: your MCP client launches it as a child process on the same machine. It works with any client that supports local stdio servers — Claude Desktop, Cursor, and the Grok CLI (grok mcp add iris -- uvx iris-mcp) among them.

It does not work with clients that only accept remote MCP connectors over HTTP. The Grok app / Grok Bot is in

... View full README on GitHub