Metadata-Version: 2.5
Name: airun-mailbox-mcp
Version: 0.1.0
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 |

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

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