Agent Email

Agent Email

English | Español | 简体中文 | Português (Brasil) | Deutsch

email-agent-mcp by UseJunior -- 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

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:

{

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

Use with Cursor

// .cursor/mcp.json

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

Use with Gemini CLI

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

Use with OpenClaw

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

{

// ... 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:

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

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

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

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 27 MCP tools; observe omits every tool whose action is marked as mailbox-mutating:

This is a shared cross-provider tool surface. Although label_email, flag_email, mark_read, and move_to_folder are advertised, the Gmail adapter intentionally does not implement those mutation capabilities. They fail closed with NOT_SUPPORTED before any Gmail mutation request. The default gmail.readonly plus gmail.compose grant would not authorize those mutations either; do not add gmail.modify to try to make the tools available. They remain available only for providers whose adapters and grants support them.

On Gmail, delete_email deletes drafts only, through users.drafts.delete, which gmail.compose authorizes. Pass either the draft id (r…) or the id of the draft's message (what list_emails with folder: "drafts" returns). The delete is permanent, because Gmail has no trash for drafts, but it still sits behind the same AGENT_EMAIL_DELETE_ENABLED gate and `user_expl