# Agent Email [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/UseJunior/email-agent-mcp  
**GitHub Stars:** 7  
**npm Downloads (last month):** 1519  
**Views:** 8  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/agent-email

## Description
Local email connectivity for AI agents — read, draft, send, and organize Outlook mail via MCP

## Tools
Capabilities this server exposes over MCP:

- **list_emails** — List recent emails with filtering by unread status, folder, sender, and limit. Use offset for pagination. A row with `isDraft: true` is an unsent draft — it has NOT been sent, and its `receivedAt` is provider-supplied metadata, not evidence of delivery. Never describe such a row as a sent, delivered, or received email.
- **read_email** — Read the full content of an email by ID, transformed to token-efficient markdown. When the response has `isDraft: true` the message is an unsent draft — it has NOT been sent, and `receivedAt` is provider-supplied metadata, not evidence of delivery; never describe it as a sent, delivered, or received email. Set format to 'html' to get the raw body HTML instead of markdown — use this when you need to preserve inline styling (colour, background-colour, underline, strikethrough) that the markdown conversion discards, e.g. to change one sentence of a formatted body and leave the rest alone. Raw HTML costs far more tokens than markdown, so leave the default alone unless you need the styling; check `bodyFormat` (`text` means the message had no HTML part, so do not send it as HTML) before writing a body back, and never write one back with `bodyTruncated: true` — you do not have the whole body. strip_quoted_history and strip_signatures are markdown-shaped text transforms and are NOT applied when format is 'html'; the HTML is returned verbatim. To write it back, call create_draft/update_draft with format: 'html' AND force_black: false — force_black defaults to true and wraps your HTML in a force-black div, so leaving it on nests another wrapper on every round trip. Set strip_quoted_history to true to drop the terminal "On … wrote:" / Outlook-header / `>`-prefix reply chain and replace it with a short marker. Set strip_signatures to true to remove detected signatures and legal disclaimers; it defaults to false here for MCP compatibility even though the core action defaults to true.
- **search_emails** — Search emails using full-text query across one or all mailboxes. Use offset for pagination. Results include unsent drafts: a row with `isDraft: true` has NOT been sent — its `receivedAt` is provider-supplied metadata, not evidence of delivery. Never describe such a row as a sent, delivered, or received email.
- **get_mailbox_status** — Get mailbox connection status, unread count, and warnings
- **list_mailboxes** — List every configured mailbox: its logical `name` (pass this as the `mailbox` argument to other tools), its `emailAddress`, provider, connection status, and which one is the default. Reports mailboxes that failed to authenticate too, so it stays useful for diagnosing a broken setup.
- **get_thread** — Retrieve all messages in a conversation thread by message ID. A thread can end with an unsent draft reply: a message with `isDraft: true` has NOT been sent, so it is not a sent reply — though earlier sent replies from the same author may exist elsewhere in the thread. Never describe such a message as a sent, delivered, or received email.
- **send_email** — Compose and send a new email. Gated by send allowlist. Draft mode bypasses allowlist. If a send fails with SEND_STATUS_UNKNOWN, the message may already have been delivered; do not resend without checking Sent Items. An identical send repeated within the duplicate window is refused with a DUPLICATE_SEND_* code instead of delivering twice; pass allow_duplicate: true only when a human has decided to send the same message again.
- **reply_to_email** — Reply to an email within an existing thread. Default reply_all=true cc's the original thread; pass reply_all=false to reply only to the sender. Send path validates all effective recipients against the send allowlist; draft path bypasses. If a send fails with SEND_STATUS_UNKNOWN, the message may already have been delivered; do not resend without checking Sent Items. An identical reply repeated within the duplicate window is refused with a DUPLICATE_SEND_* code instead of delivering twice; pass allow_duplicate: true only when a human has decided to send the same reply again.
- **create_draft** — Create an email draft with to/cc/bcc recipients. Supports body_file with YAML frontmatter (to, cc, bcc, subject, reply_to, format). Use reply_to for threaded reply drafts, where to and subject are derived from the parent message and may be omitted; pass reply_all=false with reply_to to draft a sender-only reply.
- **send_draft** — Send a previously created draft. Enforces send allowlist before sending. Rate-limited. If a send fails with SEND_STATUS_UNKNOWN, the message may already have been delivered; do not resend without checking Sent Items. Sending the same draft id twice within the duplicate window is refused with a DUPLICATE_SEND_* code instead of delivering twice; pass allow_duplicate: true only when a human has decided to send it again.
- **update_draft** — Update a draft email. Body edits are refused for reply drafts; non-reply body edits require replace_body=true and replace the body wholesale. Subject, recipients (to/cc/bcc), and attachments remain editable. Allowlist is enforced at send_draft time, not here.
- **cancel_scheduled_send** — Cancel a pending provider-held scheduled send. Only verified scheduled drafts can be cancelled.
- **list_scheduled_sends** — List pending provider-held scheduled sends for a mailbox
- **list_attachments** — List attachments for a specific email message
- **download_attachment** — Download a single attachment. By default returns inline base64 (max_size_mb default 5, ceiling 25). Pass save_to to write the file to a sandboxed local directory instead and get back only {path, filename, mimeType, size, sha256} — use this for anything large (video, audio, big PDFs) or anything local tools need as a file. File attachments only — Microsoft item/reference attachments return NOT_SUPPORTED.
- **download_message** — Save a whole message, as received, to a sandboxed local directory as a raw RFC 822 .eml file (Graph /$value, Gmail format=raw). Returns {path, filename, mimeType, size, sha256}, never the bytes. Use it to keep a record copy next to attachments saved with download_attachment save_to.
- **label_email** — Apply labels or categories to one or more emails
- **flag_email** — Flag or unflag an email as important/starred
- **mark_read** — Mark an email as read or unread
- **delete_email** — Delete an email (disabled by default, requires explicit configuration). On Gmail only drafts can be deleted under the default scopes, and a draft delete is permanent (Gmail has no trash for drafts); deleting sent or received Gmail mail returns NOT_SUPPORTED.
- **move_to_folder** — Move an email to a specific folder (inbox, archive, trash, etc.). Returns the new message ID since Graph assigns a new ID after moving.
- **list_folders** — Recursively list mail folders, including computed paths for nested folders
- **create_folder** — Create a custom child mail folder (defaults to a child of Inbox)
- **delete_folder** — Delete a custom mail folder, including any mail it contains (disabled by default, requires explicit configuration). Well-known/system folders are protected.
- **list_inbox_rules** — List server-side inbox rules with all fields reported by the provider
- **create_inbox_rule** — Create a persistent server-side inbox rule using safe actions only; forwarding, redirection, and deletion are blocked. Confirm with the user before calling — this creates a rule that keeps acting on the mailbox 24/7 after the session ends.
- **delete_inbox_rule** — Delete a server-side inbox rule by id (disabled by default, requires explicit configuration). Removing a rule can silently re-expose the mailbox to mail the rule was filtering.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## What Agent Email does

Agent Email gives MCP-compatible runtimes access to configured Microsoft 365/Outlook and Gmail mailboxes. It can retrieve recent messages, search across mailboxes, read full message content, inspect conversation threads, and report mailbox status. Mailbox selection is explicit: `list_mailboxes` returns logical mailbox names, addresses, providers, connection states, and the default mailbox.

The server also covers common mailbox actions. Agents can create, edit, send, and reply to messages; apply labels or categories; change read and important/starred state; move messages between folders; and manage custom folders. Additional tools expose attachments, raw RFC 822 message downloads, scheduled sends, and server-side inbox rules.

## How it works

Run the package locally over MCP stdio. The setup wizard guides OAuth configuration and mailbox selection, after which an MCP client invokes the email tools. A default `full` scope profile exposes read and write operations. Setting `EMAIL_AGENT_MCP_SCOPE_PROFILE=observe` before configuration and startup provides read-focused access and removes mailbox-mutating tools from the MCP surface.

Message bodies normally come back as token-efficient Markdown. HTML can be requested when inline formatting must be preserved, but HTML should only be written back when the complete, non-truncated body is available. Draft and send operations distinguish unsent drafts from delivered messages. Send and reply operations also detect duplicate attempts and report uncertain delivery states so an agent can check Sent Items before retrying.

## Setup and configuration

Start the interactive setup with:

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

The server can be added to Claude Code or Cursor as a stdio MCP process using `npx -y email-agent-mcp`. Gemini CLI can install it from the GitHub repository. OpenClaw can run the package through an MCP `stdio` configuration; its `mcp` configuration key requires a sufficiently recent OpenClaw app.

Configure a send allowlist before enabling outbound mail. Delete operations are disabled by default and require explicit configuration. The `full` profile requests Microsoft delegated permissions for reading, writing, sending, mailbox settings, user identity, and offline access; `observe` requests a narrower read-oriented set. Changing profiles may require renewed consent, and an already granted token can retain previously consented write permissions.

## Tools and capabilities

- List, filter, paginate, search, and read messages across configured mailboxes.
- Retrieve complete conversation threads and distinguish draft messages from sent mail.
- Create, update, send, and reply to drafts, including threaded replies and recipient controls.
- Apply labels, mark messages read or unread, flag them, and move them between folders.
- Inspect, download, and save attachments or whole messages as sandboxed files.
- List or cancel provider-held scheduled sends.
- Create, inspect, and delete inbox rules using restricted actions; forwarding, redirection, and deletion actions are blocked when creating rules.

## Limitations and notes

The observation profile reduces the available MCP tools but is not always an OAuth boundary when a mailbox previously received broader consent. Gmail draft deletion is permanent under the default scopes, while deleting sent or received Gmail messages is unsupported. Folder moves can produce a new message ID with Microsoft Graph.

Attachment downloads return inline base64 by default, with a default 5 MB limit and a 25 MB ceiling; saving to a sandboxed directory returns file metadata instead. Microsoft item/reference attachments are unsupported. Inbox rules continue acting after the agent session ends, so rule creation requires user confirmation.

If a send or reply returns an unknown status, delivery may already have occurred. Check Sent Items before retrying. Repeated identical sends are refused within the duplicate window unless a human explicitly permits the duplicate.

_Full upstream README: https://allmcps.com/mcp/agent-email/readme_