email-agent-mcp

# Agent Email

[![npm version](https://img.shields.io/npm/v/email-agent-mcp)](https://www.npmjs.com/package/email-agent-mcp)
[![npm downloads](https://img.shields.io/npm/dm/email-agent-mcp.svg)](https://npmjs.org/package/email-agent-mcp)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![CI](https://github.com/UseJunior/email-agent-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/UseJunior/email-agent-mcp/actions/workflows/ci.yml)
[![codecov](https://img.shields.io/codecov/c/github/UseJunior/email-agent-mcp/main)](https://app.codecov.io/gh/UseJunior/email-agent-mcp)
[![GitHub stargazers](https://img.shields.io/github/stars/UseJunior/email-agent-mcp?style=social)](https://github.com/UseJunior/email-agent-mcp/stargazers)
[![Tests: Vitest](https://img.shields.io/badge/tests-vitest-6E9F18)](https://vitest.dev/)
[![OpenSpec Traceability](https://img.shields.io/badge/openspec-traceability%20gate-brightgreen)](./scripts/check-spec-coverage.mjs)
[![Socket Badge](https://socket.dev/api/badge/npm/package/email-agent-mcp)](https://socket.dev/npm/package/email-agent-mcp)
[![install size](https://img.shields.io/npm/unpacked-size/email-agent-mcp)](https://www.npmjs.com/package/email-agent-mcp)

[English](./README.md) | [Español](./README.es.md) | [简体中文](./README.zh.md) | [Português (Brasil)](./README.pt-br.md) | [Deutsch](./README.de.md)

**email-agent-mcp** by [UseJunior](https://usejunior.com?utm_source=github&utm_medium=readme&utm_campaign=email-agent-mcp) -- local email connectivity for AI agents.

Agent Email is an open-source TypeScript MCP server that lets Claude Code, Cursor, Gemini CLI, OpenClaw, and other MCP-compatible runtimes read email, search threads, draft replies, label messages, change read state, move messages, and send mail through your own mailbox. Microsoft 365 / Outlook and Gmail are supported today. Security-first defaults mean agents cannot send email until you explicitly configure an allowlist.

## Quick Start

```bash
npx -y email-agent-mcp
```

The interactive setup wizard walks you through OAuth configuration and mailbox selection.

## What Works Today

- Microsoft 365 / Outlook mailbox access through MCP stdio
- `list_emails`, `read_email`, `search_emails`, and `get_thread`
- `create_draft`, `update_draft`, `send_draft`, `send_email`, and `reply_to_email`
- `label_email`, `mark_read`, and `move_to_folder`
- send allowlists, delete disabled by default, and sanitized errors

The current launch-prep pass was validated against a real Outlook mailbox for read, draft, send, categorize, move, and read-state flows.

## Why This Exists

AI agents need to read, reply to, and act on email, but email APIs are complex. OAuth flows, Graph delta queries, Gmail push subscriptions, HTML-to-markdown conversion, threading semantics -- each provider has its own quirks.

Agent Email wraps this complexity into deterministic MCP tools with security guardrails:

- send and receive allowlists that control who agents can contact
- delete disabled by default (requires explicit opt-in)
- error sanitization that strips API keys, file paths, and stack traces
- body file sandboxing with path traversal protection

## Use with Claude Code

Add to `~/.claude/settings.json` or your project `.claude/settings.json`:

```json
{
  "mcpServers": {
    "email-agent-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "email-agent-mcp"]
    }
  }
}
```

## Use with Cursor

```json
// .cursor/mcp.json
{
  "mcpServers": {
    "email-agent-mcp": {
      "command": "npx",
      "args": ["-y", "email-agent-mcp"]
    }
  }
}
```

## Use with Gemini CLI

```bash
gemini extensions install https://github.com/UseJunior/email-agent-mcp
```

## Use with OpenClaw

Add an `mcp` block to `~/.openclaw/openclaw.json`:

```json5
{
  // ... existing config ...
  mcp: {
    servers: {
      email: {
        command: "npx",
        args: ["tsx", "/path/to/email-agent-mcp/packages/email-mcp/src/serve-entry.ts"],
        transport: "stdio"
      }
    }
  }
}
```

> **Version note**: The `mcp` config key requires OpenClaw app >= 2026.3.24. If the CLI is older than the app, it may reject this key during validation even though the gateway accepts it. Update the CLI with `npm install openclaw@latest` in your NemoClaw directory, or restart the gateway directly with `launchctl kickstart -k gui/501/ai.openclaw.gateway`.

### Email watcher

The watcher polls your mailbox and sends wake signals to OpenClaw when new email arrives:

```bash
# Set the hooks token (must match hooks.token in openclaw.json)
export OPENCLAW_HOOKS_TOKEN="your-hooks-token"

# Start the watcher (defaults to http://localhost:18789/hooks/wake)
npm run dev:watch
```

The watcher requires at least one configured mailbox. Run `npx email-agent-mcp` or `npm run dev:configure` first to complete the OAuth flow.

## Launch Prep Smoke Test

Before recording a demo, run the live smoke script against a real mailbox and a safe send allowlist. The script exercises:

- `get_mailbox_status`
- `list_emails` + `read_email`
- `mark_read` unread -> read -> unread
- `label_email` on a safe inbox candidate
- `create_draft`
- draft-only `reply_to_email`
- optional `send_email`

Example:

```bash
EMAIL_AGENT_MCP_HOME=/tmp/email-agent-mcp-live \
AGENT_EMAIL_SEND_ALLOWLIST=/tmp/email-agent-mcp-live/send-allowlist.json \
npm run launch:prep:smoke -- --live-write --send-to beta@usejunior.com
```

Default safe-candidate selection looks for `notifications@github.com` in the inbox so you can rehearse the recording flow on a public-safe message instead of customer mail.
If your mailbox status name is not an email address, pass `--reply-sender <email>` or set `EMAIL_AGENT_MCP_REPLY_SENDER` so the script can find a self-sent message for the draft-reply check.

## Tool Reference

### Scope profiles

Set `EMAIL_AGENT_MCP_SCOPE_PROFILE` before configuring and starting the server to
choose the permissions exposed to an agent. The default is `full` for backward
compatibility.

| Profile | Microsoft delegated scopes | Exposed tools |
|---------|-----------------------------|---------------|
| `observe` | `Mail.Read`, `User.Read`, `offline_access` | Read-only email tools, minus `list_inbox_rules` (see below) |
| `full` (default) | `Mail.Read`, `Mail.ReadWrite`, `Mail.Send`, `MailboxSettings.ReadWrite`, `User.Read`, `offline_access` | All tools |

For an observation-only deployment, set the profile for both configuration and
runtime so the OAuth consent and MCP tool list agree:

```bash
export EMAIL_AGENT_MCP_SCOPE_PROFILE=observe
npx email-agent-mcp configure
npx email-agent-mcp serve
```

`observe`'s scopes are a deliberate **strict subset** of `full`'s. That is what
makes the profile adoptable: a tenant that has already consented to the full set
grants `observe` silently, so switching `full` → `observe` needs no new consent.
Switching `observe` → `full` does require a new interactive consent, because it
asks for scopes that were never granted.

For the same reason `observe` does **not** expose `list_inbox_rules`. Graph gates
`/mailFolders/inbox/messageRules` behind `MailboxSettings`, and Entra treats
`MailboxSettings.Read` as a distinct scope from `full`'s
`MailboxSettings.ReadWrite` rather than implied by it. Requesting it would break
the subset property and force a fresh consent on every `observe` deployment — an
admin-approval request in tenants that restrict user consent. Use `full` if you
need inbox-rule visibility.

An invalid profile value stops startup instead of silently granting broader
access. If cached credentials do not cover the profile's scopes, the server
fails fast with an actionable error rather than blocking on an interactive
sign-in.

#### What `observe` does and does not guarantee

`observe` always removes the write tools from the MCP tool surface, so an agent
cannot invoke them. That part holds everywhere.

It only narrows the **OAuth token** on a mailbox that has not already consented
to the write scopes. Entra issues an access token carrying every scope the user
or tenant has already consented to for that application — not just the subset
requested at token-acquisition time. So if you point `observe` at a mailbox
previously configured as `full`, the underlying token still carries
`Mail.ReadWrite` and `Mail.Send`; only the tool surface is reduced.

For a genuine least-privilege token, consent to `observe` from a mailbox that
has never been granted the write scopes — a fresh `configure` against an app
registration whose delegated permissions stop at `Mail.Read`/`User.Read`. Treat
the tool-surface reduction as defense in depth, not as an OAuth boundary, unless
you control the grant.

### Tools

The `full` profile exposes 26 MCP tools; `observe` omits every tool whose action
is marked as mailbox-mutating:

| Tool | Description | Type |
|------|-------------|------|
| `list_emails` | List recent emails with filtering | read |
| `read_email` | Read full email content as markdown, or raw HTML with `format: "html"` | read |
| `search_emails` | Full-text search across mailboxes | read |
| `list_mailboxes` | Enumerate configured mailboxes, their status, and the default | read |
| `get_mailbox_status` | Connection status and warnings | read |
| `get_thread` | Full conversation context | read |
| `list_attachments` | List attachment metadata for an email | read |
| `download_attachment` | Download a file attachment as base64 | read |
| `send_email` | Send new email (allowlist-gated) | write |
| `reply_to_email` | Reply within thread (allowlist-gated on send) | write |
| `create_draft` | Create email draft | write |
| `update_draft` | Update draft content | write |
| `send_draft` | Send a saved draft | write |
| `list_scheduled_sends` | List pending provider-held scheduled sends (Microsoft 365) | read |
| `cancel_scheduled_send` | Cancel a pending scheduled send (Microsoft 365) | destructive |
| `label_email