Metadata-Version: 2.5
Name: airun-mailbox-mcp
Version: 0.1.3
Summary: Read-only MCP server for Exchange Online mailboxes over IMAP OAuth (client credentials)
Author: Ihor Skostariev
License-Expression: MIT
License-File: LICENSE
Keywords: email,exchange,imap,mcp,model-context-protocol,office365,outlook
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: mcp<3,>=2.3
Description-Content-Type: text/markdown

# airun-mailbox-mcp

A **read-only** [Model Context Protocol](https://modelcontextprotocol.io) 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

| Tool | Purpose |
| --- | --- |
| `list_folders` | All folders (Inbox, Sent Items, subfolders, ...) |
| `list_messages(folder, limit, offset, unread_only)` | Header summaries, newest first, with paging (up to 50 per call) |
| `search_messages(folder, text, sender, recipient, subject, body, since, before, unread_only, limit)` | IMAP SEARCH; dates are `YYYY-MM-DD`; non-ASCII text is supported |
| `get_message(uid, folder, max_chars)` | Headers, readable body (HTML is converted to text) and the attachment list |
| `diagnose()` | Checks config, DNS, ports 443/993, the token request and the IMAP login; returns a report with a hint (never fails) |

## 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:

   ```powershell
   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](https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth).

## Configuration

| Variable | Description |
| --- | --- |
| `TENANT_ID` | Entra ID tenant (directory) ID |
| `CLIENT_ID` | Application (client) ID |
| `CLIENT_SECRET` | Client secret value |
| `MAILBOX_UPN` | Mailbox to read, e.g. `support@example.com` |

## Install and run

```sh
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

```sh
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

```json
{
  "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 the console only, on **stderr** (stdout carries the MCP protocol). The server never writes log files. 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.

| Option | Env variable | Default | Purpose |
| --- | --- | --- | --- |
| `--log-level DEBUG` | `AIRUN_LOG_LEVEL` | `INFO` | `DEBUG` also logs when each step starts, so you can see where a hang begins |
| – | `AIRUN_IMAP_TIMEOUT` | `20` | Seconds per IMAP socket operation |
| – | `AIRUN_TOKEN_TIMEOUT` | `15` | Seconds for the token request |
| – | `AIRUN_LOG_MCP=1` | off | Include the MCP SDK's DEBUG logs, which contain full JSON-RPC messages including email content |

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

```sh
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

```sh
uv sync
uv run pytest
uv build
```

## License

MIT
