airun-mailbox-mcp

A read-only Model Context Protocol server that lets AI assistants (Claude Code, Claude Desktop, any MCP client) read an Exchange Online mailbox. It authenticates as an Entra ID application (OAuth client credentials) and talks to Exchange Online over IMAP with XOAUTH2, so no user sign-in is needed.

Folders are opened with EXAMINE and messages are fetched with BODY.PEEK, so the server never changes the mailbox: it doesn't mark messages as read, move them or delete them.

Tools

Prerequisites (Entra ID / Exchange admin)

1. Register an app in Entra ID and create a client secret.

2. Add the Office 365 Exchange Online → IMAP.AccessAsApp application permission and grant admin consent.

3. In Exchange Online PowerShell, register the app's service principal and give it access to the mailbox:

   New-ServicePrincipal -AppId <CLIENT_ID> -ObjectId <ENTERPRISE_APP_OBJECT_ID>
   Add-MailboxPermission -Identity <MAILBOX_UPN> -User <ENTERPRISE_APP_OBJECT_ID> -AccessRights FullAccess
   

4. Make sure IMAP is enabled for that mailbox.

See Microsoft's guide: Authenticate an IMAP, POP or SMTP connection using OAuth.

Configuration

Install and run

uvx airun-mailbox-mcp              # run without installing (recommended)
pip install airun-mailbox-mcp      # or install into an environment
airun-mailbox-mcp --transport streamable-http --port 8000   # HTTP at http://127.0.0.1:8000/mcp

stdio is the default transport. The streamable-http transport has no authentication, so bind it only to localhost or put it behind an authenticating proxy.

Claude Code

claude mcp add airun-mailbox --scope user \
  -e TENANT_ID=... -e CLIENT_ID=... -e CLIENT_SECRET=... -e MAILBOX_UPN=... \
  -- uvx airun-mailbox-mcp

To keep the secret out of ~/.claude.json, store the variables in a chmod 600 env file (see .env.example) and use -- uvx --env-file /path/to/.env airun-mailbox-mcp instead.

Claude Desktop / other MCP clients

{
  "mcpServers": {
    "airun-mailbox": {
      "command": "uvx",
      "args": ["airun-mailbox-mcp"],
      "env": {
        "TENANT_ID": "...",
        "CLIENT_ID": "...",
        "CLIENT_SECRET": "...",
        "MAILBOX_UPN": "support@example.com"
      }
    }
  }
}

Command-line helper

airun-fetch-messages [--mailbox UPN] [--limit 1-10] prints the newest Inbox messages as JSON. You can use it to check the credentials before you set up an MCP client.

Logging and troubleshooting

Logs go to stderr (stdout carries the MCP protocol). Each tool call logs its arguments, every network step (DNS, IMAP connect, token request, login, folder open, search, fetch) with its duration, and the result or error. Secrets and tokens are never logged.

Test connectivity from the machine or container that runs the server:

airun-mailbox-mcp --check --log-level DEBUG

It runs the same checks as the diagnose tool, prints the JSON report and exits with code 0 on success. A timeout shows up as a tool error naming the step that failed (for example network timeout during 'imap connect'). This usually means outbound TCP to outlook.office365.com:993 is blocked. IMAP does not use HTTPS_PROXY.

Security notes

• An app with IMAP.AccessAsApp can read every mailbox it has been granted access to. Grant FullAccess only on the mailboxes you need.
• Email content is untrusted input. The server tells clients not to follow instructions found in messages, but treat what the model reads with care.
• Never commit secrets. .env is ignored by git and is not included in the package.

Development

uv sync
uv run pytest
uv build

License

MIT