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, andget_threadcreate_draft,update_draft,send_draft,send_email, andreply_to_emaillabel_email,mark_read, andmove_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
mcpconfig 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 withnpm install openclaw@latestin your NemoClaw directory, or restart the gateway directly withlaunchctl 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_statuslist_emails+read_emailmark_readunread -> read -> unreadlabel_emailon a safe inbox candidatecreate_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 [email protected]
Default safe-candidate selection looks for [email protected] 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.
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_explicitly_requested_deletion flag; it does not need
AGENT_EMAIL_HARD_DELETE_ENABLED. Deleting a sent or received Gmail message
returns NOT_SUPPORTED, since it would need gmail.modify. update_draft
likewise accepts either id on Gmail. Gmail gives a draft a new message id every
time it is updated, while its draft id stays the same, so prefer the draft id
(or list the drafts again) after an edit.
Every row returned by list_emails, search_emails, and get_thread, and the
read_email response, carries an always-present isDraft boolean. isDraft: true
means the message is an unsent draft: it has not been sent, and its receivedAt
is provider-supplied metadata rather than evidence of delivery. The field is never
omitted, so a consuming agent can distinguish "not a draft" from "draft status not
reported" — but note false asserts only that the provider did not mark the message
as an unsent draft, not that the mailbox owner sent it (received mail is also
false). Drafts otherwise appear in listings and search results as before.
Folder and inbox-rule management requires Microsoft Graph MailboxSettings.ReadWrite consent. Existing Microsoft mailbox connections must re-consent after upgrading. Gmail uses labels rather than hierarchical folders/server-side Exchange rules, so these six tools return NOT_SUPPORTED for Gmail mailboxes.
Body formats
Bodies cross the wire as markdown by default in both directions. That default is deliberate — markdown is token-efficient, and a routine read should stay cheap. Both directions can opt out of it.
Writing — send_email, reply_to_email, create_draft, and update_draft
accept an optional format:
html is unsanitised passthrough: no sanitiser, no allowlist, no rewriting of
your markup. Inline CSS and arbitrary tags survive to the wire — that is what
makes styled mail possible, and it means you own whatever you send. The one
default modification is the force-black wrapper below; with force_black: false the body passes through byte-for-byte.
For markdown and html the rendered HTML is wrapped in a
<div style="color: #000000;"> so Outlook's dark mode does not turn the text
white-on-white.
Body files — send_email, create_draft, and update_draft also accept
body_file: a path to a .md, .html, or .txt file (read relative to
EMAIL_MCP_SAFE_DIR, default the process working directory, plus any
AGENT_EMAIL_ALLOWED_DIRS roots) used as the body
instead of body. A .md body file may
open with a YAML frontmatter block:
For update_draft, body and body_file are permitted only on a non-reply
draft and require replace_body: true; the stored body is then replaced
wholesale. Reply draft bodies cannot be edited safely because they include
provider-assembled quoted history, so create a new draft instead. Subject,
recipient, and attachment updates remain available on reply drafts.
---
to: [email protected]
subject: Quarterly summary
format: html
force_black: false
---
<p>The body starts after the closing delimiter.</p>
Recognized keys are to, cc, bcc, subject, reply_to, draft, format,
and force_black (draft: true turns a send_email call into a draft save).
bcc applies to create_draft and update_draft; send_email refuses a body
file that sets it rather than sending without the Bcc. A
frontmatter value overrides the same-named tool parameter. Frontmatter is
parsed only from .md files, and the file extension never selects the format —
without an explicit format tool parameter, even a .html body file gets the
default markdown rendering; pass format: "html" for passthrough.
Reading — read_email accepts an optional format of markdown (default)
or html:
{ "id": "AAMkAD...", "format": "html" }
format: "html" returns the message's raw body HTML verbatim. Reach for it when
you need styling that markdown cannot carry — color, background-color,
text-decoration, <u> — for example to change one sentence of a formatted body
and leave the rest alone. Through the markdown path that styling is silently
destroyed on the way out.
Two fields come back with it:
bodyFormat— always present:markdown,html, ortext. You gettextwhen you asked forhtmlbut the message has no HTML part, in which case the plain-text body is returned. Check this before writing a body back.bodyTruncated— present andtrueonly if the body exceeded the 256 KB response budget forformat: "html"(the markdown path is unbounded, as before). Do not write a truncated body back to a draft.
Raw HTML costs far more tokens than its markdown reduction, so leave the default
alone unless you need the styling. strip_quoted_history and strip_signatures
are markdown-shaped text transforms and are not applied when format is html —
the raw HTML is returned untouched.
Writing it back. Pass format: "html" and force_black: false:
{ "draft_id": "AAMkAD...", "body": "<edited html>", "format": "html", "force_black": false }
force_black defaults to true, which wraps whatever HTML you send in a
<div style="color: #000000;">. That is right for HTML you authored yourself,
but on a body you just read back it nests one more wrapper on every cycle — after
fifteen revisions you have fifteen nested divs. With force_black: false the
bytes survive the round trip untouched.
Scheduled send
send_email and send_draft accept scheduled_send_at, an ISO 8601 future
timestamp with an explicit timezone. Microsoft 365 holds the message
server-side, so delivery survives this process exiting. Use the returned
messageId with cancel_scheduled_send while it is pending, or inspect pending
items with list_scheduled_sends. That listing covers messages you scheduled
from Outlook itself, not just ones scheduled through this server — Outlook parks
the held message wherever it likes (often Deleted Items), so discovery scans the
mailbox rather than a folder, and reports only sends whose time is still ahead.
Microsoft Graph changes the message ID when the held draft moves to Sent Items,
so the returned ID is a pre-delivery management handle, not a permanent sent
message ID. Gmail's public API does not expose scheduled send; all scheduled
send surfaces return NOT_SUPPORTED for Gmail while immediate sends remain
unchanged.
Outbound attachments
send_email, reply_to_email, create_draft, and update_draft accept an
optional attachments array. Each entry takes a sandboxed file path (read
relative to EMAIL_MCP_SAFE_DIR, default the process working directory, plus
any AGENT_EMAIL_ALLOWED_DIRS roots — see below) or
inline base64, plus optional filename / mimeType overrides:
{
"to": "[email protected]",
"subject": "Signed agreement",
"body": "Attached as requested.",
"attachments": [
{ "path": "./out/agreement.pdf" },
{ "base64": "iVBORw0KGgo...", "filename": "screenshot.png" }
]
}
Files are capped at 25MB each. Microsoft Graph automatically uses chunked
upload sessions when a file does not fit its small inline request path; Gmail
automatically uses raw MIME media upload when the message exceeds 5MB. Both
strategies work for sends, replies, and draft create/update operations. For
update_draft, omitting attachments preserves the draft's existing files;
passing an array (even empty) replaces them.
Attaching files from outside the working directory — set
AGENT_EMAIL_ALLOWED_DIRS to a delimiter-separated list of absolute
directories (: on macOS/Linux, ; on Windows; a leading ~ is expanded) that
attachments[].path and body_file may also read from:
{
"mcpServers": {
"email-agent-mcp": {
"command": "npx",
"args": ["-y", "@usejunior/email-agent-mcp"],
"env": { "AGENT_EMAIL_ALLOWED_DIRS": "~/Downloads:/Volumes/Shared/Contracts" }
}
}
}
How a caller's path is resolved — the two rules below both surface as
FILE_NOT_FOUND, which is easy to misread as a missing file:
The ~ shorthand is expanded in AGENT_EMAIL_ALLOWED_DIRS (the operator's
config) but not in attachments[].path or body_file (the caller's
argument) — pass those as absolute paths. And a relative path is deliberately
confined to the safe directory: searching every allowed root for a bare
contract.pdf would silently attach whichever copy happened to exist first.
Each root is canonicalised with realpath before the containment check: an
allowlisted root that is itself a symlink resolves to its real location, a root
that cannot be canonicalised authorises nothing, and a symlink escaping every
root is still rejected. Unset (the default) keeps the working directory as the
only root — which is why an agent that cannot reach a file should ask you to
allowlist its directory rather than copy confidential documents into a git
working tree.
Allowlisting a directory trusts everyone who can write to it. Validation and
open are separate operations on a path, so a principal who can replace a
directory inside an allowed root between the two can still redirect the read;
only allowlist roots whose ancestors are not writable by untrusted users. The
final file is opened with O_NOFOLLOW, so the file itself cannot be swapped for
a symlink after validation.
Saving attachments and messages to disk
download_attachment returns inline base64 by default (5 MB default cap, 25 MB
ceiling). Pass save_to to have the server write the file instead. You get back
only metadata, so large attachments (screen recordings, audio, big PDFs) never
pass through the agent's context:
{ "message_id": "…", "attachment_id": "…", "save_to": "/Users/you/Downloads/records" }
{ "success": true, "path": "/Users/you/Downloads/records/Signed_Agreement.pdf",
"filename": "Signed_Agreement.pdf", "original_filename": "Signed Agreement.pdf",
"mimeType": "application/pdf", "size": 782957, "sha256": "…" }
download_message writes a message as received, as raw RFC 822 MIME (Graph
/$value, Gmail format=raw), to <subject>.eml and returns the same
metadata. Use it to keep a record copy next to the attachments.
save_to names a directory and resolves exactly like body_file and
attachments[].path. Relative paths resolve against EMAIL_MCP_SAFE_DIR, and
AGENT_EMAIL_ALLOWED_DIRS roots need absolute paths. .., a leading ~, and
symlinks that escape the sandbox are rejected. Missing subdirectories are
created. An existing file is never overwritten: a name collision gets a numeric
suffix (report.pdf, report-1.pdf, …). Files are created with mode 0600.
size and sha256 describe the exact bytes written, which can differ slightly
from the size list_attachments reports, since providers count MIME
overhead. With save_to, the default and ceiling for max_size_mb are 150 MB.
An inline download over the cap fails with ATTACHMENT_TOO_LARGE and a hint
to use save_to.
Provider Support
Use email-agent-mcp configure --provider gmail to run the local browser OAuth flow, or add a manual mailbox token file under ~/.email-agent-mcp/tokens/. See Gmail Setup below and packages/provider-gmail/README.md.
Gmail Setup
Gmail has two supported OAuth paths. Both end with the same result: a refresh token on your machine, and Gmail API calls going directly from your machine to Google.
Recommended for now: BYOK. Our default OAuth client is still in Google's "Testing" publishing status while verification is in progress, which caps it at 100 registered test users and shows the "Google hasn't verified this app" interstitial during consent. Verification for Gmail's restricted scope requires a CASA security assessment and takes several weeks; progress is tracked in issue #112. BYOK sidesteps the shared 100-user cap and puts the app's publishing status under your control; your own app still has Google's Testing constraints until you publish it.
Other reasons to pick BYOK: dedicated API quota, your own privacy policy and
verification status, and no dependency on the hosted broker at
https://oauth.usejunior.com.
Scopes requested
Agent Email requests exactly these two Gmail scopes by default:
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.compose
gmail.readonly is required for reading messages and threads;
gmail.compose manages drafts and sending but does not authorize
users.threads.get or users.messages.get. The default grant does not include
gmail.modify. Separately, the Gmail adapter intentionally leaves label
changes, read-state changes, moves, trash, and deletion of sent or received
mail unsupported, so those tools fail closed with NOT_SUPPORTED. Deleting a
draft works under the default grant. Add both scopes to your OAuth
consent screen.
Deployments that explicitly set GMAIL_OAUTH_SCOPES must update it to the two
space-separated scopes above. New authorizations and repeated authorizations
must re-consent to the new scope pair. Existing mailbox files and their stored
refresh-token metadata remain unchanged.
BYOK: create your own Google OAuth client
- Create a project in the Google Cloud Console, or select an existing one.
- Enable the Gmail API under APIs & Services → Library → Gmail API → Enable.
- Configure the OAuth consent screen under APIs & Services → OAuth consent screen:
- User type External for a personal
@gmail.comaccount, or Internal if you are on Google Workspace and only your own org needs access. - Add both
https://www.googleapis.com/auth/gmail.readonlyandhttps://www.googleapis.com/auth/gmail.compose. - While the app is in Testing, add your own Gmail address under Test users, or consent will be refused.
- User type External for a personal
- Create the OAuth client under APIs & Services → Credentials → Create
credentials → OAuth client ID. Choose application type Desktop app.
Desktop is required:
configurestarts a throwaway listener on an ephemeral loopback port (http://127.0.0.1:<port>/oauth2callback), and only Desktop clients let Google accept an arbitrary loopback port without pre-registering the exact redirect URI. A Web application client will fail withredirect_uri_mismatch. - Copy the client ID and client secret.
BYOK: hand the credentials to email-agent-mcp
Pass both halves as flags:
npx email-agent-mcp configure \
--provider gmail \
--mailbox personal \
--client-id YOUR_GOOGLE_CLIENT_ID \
--client-secret YOUR_GOOGLE_CLIENT_SECRET
Or set the two namespaced environment variables and omit the flags:
export AGENT_EMAIL_GMAIL_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID
export AGENT_EMAIL_GMAIL_CLIENT_SECRET=YOUR_GOOGLE_CLIENT_SECRET
npx email-agent-mcp configure --provider gmail --mailbox personal
Both halves are required. Supplying only one exits with an error rather than silently falling back to the default client. Supplying neither selects the default OAuth client.
Your browser opens Google's consent screen, the CLI catches the callback on
loopback, exchanges the code with PKCE, and writes the mailbox to
~/.email-agent-mcp/tokens/<safe-key>.json with "source": "byok" alongside
your clientId, clientSecret, and the resulting refreshToken. Token
refreshes then go straight to Google's token endpoint; no broker is involved.
Re-running configure for a mailbox that is already saved reuses the saved
credentials, so you only pass the flags once. Passing --client-id and
--client-secret for a mailbox previously configured against the default
client migrates it to BYOK.
BYOK: keep the grant from expiring after 7 days
Google expires refresh tokens after 7 days while your OAuth app is in
Testing publishing status, which shows up as a re-authentication prompt about
once a week. email-agent-mcp status warns when a mailbox is approaching that
window. Publishing your app (OAuth consent screen → Publish app) removes the
7-day expiry. Since you own the app and are its only user, the 100-user test
cap does not apply to you either way.
Disconnect Gmail and revoke access
Disconnecting has two independent parts:
- Stop any running
email-agent-mcpprocess. In Finder, open~/.email-agent-mcp/tokens/, identify the single JSON file for the mailbox you intend to disconnect, and move that exact file to Trash. Do not open, paste, or share its contents, and do not delete the whole~/.email-agent-mcpdirectory if other mailboxes are configured. If you setEMAIL_AGENT_MCP_HOME, use that directory'stokens/folder instead. - Open Google Account third-party connections, select Email Agent MCP (or the name of your BYOK application), and remove its access.
Deleting the local file prevents this installation from using the saved
credential. Removing the Google Account connection revokes the grant at
Google. Run email-agent-mcp status afterward to confirm the mailbox is no
longer configured.
Security Defaults
Agent Email ships with restrictive defaults that you loosen as needed:
- Send allowlist: empty by default -- agents cannot send email until you add recipients
- Receive allowlist: accepts all by default -- controls which senders trigger the watcher
- Delete disabled: agents cannot delete email by default. Two gates must both be satisfied:
- operator sets
AGENT_EMAIL_DELETE_ENABLED=truein the email-agent-mcp process environment (andAGENT_EMAIL_HARD_DELETE_ENABLED=truefor permanent deletion). Restart required after change. Gmail can delete only drafts, and a draft delete is always permanent; it needs onlyAGENT_EMAIL_DELETE_ENABLED. - the caller passes
user_explicitly_requested_deletion: trueon the tool call.
- operator sets
- Error sanitization: API keys, file paths, and stack traces are redacted from error responses
- Body file sandboxing: no
../traversal, no symlinks, binary detection - Duplicate-delivery guard: on by default -- an identical send, reply, or draft-send repeated within 15 minutes is refused instead of delivered twice
Duplicate-delivery guard
Provider send endpoints (Graph POST /sendMail, Gmail users.messages.send) take no
idempotency key, so Agent Email dispatches each delivery exactly once and never retries
one automatically. That stops the library from duplicating a message. It does not stop
the caller: an agent whose tool result was lost -- a compacted context, a dropped
transport, a supervisor restarting the turn, a person retrying something that looked
stuck -- replays the same approved instruction, and the second call looks exactly like a
first one.
send_email, reply_to_email, and send_draft therefore record each dispatch in an
in-process ledger, keyed by a digest of the effective action inputs -- mailbox,
recipients, subject, rendered body, attachment contents, and the reply parent or draft
id. (Effective inputs, not final wire bytes: a provider may transform a message on
the way out, and Graph for instance truncates a subject at 255 characters, so two
different inputs can leave as identical mail. The guard catches a replayed tool call,
which is what actually happens.) A repeat within the window is refused before the
delivery is dispatched:
A failure that proves nothing was delivered -- any 4xx-derived code, a 429, or a connect failure -- releases the record immediately, so resending after a rejection is never blocked. Anything else, including a code from a provider we have not seen, is held as unresolved: a wrongly-held message costs one blocked resend, a wrongly-released one costs a duplicate in somebody's inbox.
To send the same message again on purpose, pass allow_duplicate: true. It is an
unconditional per-request bypass -- a replay that also carries the flag dispatches
again, because the flag asserts that a person decided on this send. The forced attempt
is recorded alongside the earlier one rather than replacing it, so if the override is
rejected the original delivery still refuses an ordinary replay.
Records are scoped to a mailbox: mailbox when the caller supplies one, otherwise the
provider instance. Operators can change the window with
AGENT_EMAIL_DUPLICATE_SEND_WINDOW_MS (default 900000); 0 disables the guard
entirely.
The ledger lives in the server process and in memory. It closes the replay window that actually happens -- a retry inside a running server -- and does not survive restarting that server.
Packages
Quality and Trust Signals
- CI runs on every pull request and push to main (lint, typecheck, tests on Node 20 + 22)
- CodeQL and Semgrep security scanning
- Coverage published to Codecov
- OpenSpec traceability enforcement via
npm run check:spec-coverage - 300+ tests across the suite
- Maintainer: Steven Obiajulu
Architecture
email-agent-mcp/
├── packages/
│ ├── email-core Core actions, content engine, security
│ ├── email-mcp MCP server adapter, CLI, watcher
│ ├── provider-microsoft Microsoft Graph provider
│ ├── provider-gmail Gmail API provider
│ └── email-agent-mcp Distribution wrapper (npx entry point)
├── openspec/ Spec-driven development
└── scripts/ CI and validation scripts
Releasing
Tag-driven release via GitHub Actions with npm OIDC trusted publishing. All 6 packages publish in dependency order with --provenance, then server.json is published to the official MCP Registry with mcp-publisher.
FAQ
Does this work with Claude Code?
Yes. Run npx email-agent-mcp to start the MCP server, then configure it in your Claude Code settings.
Can agents send email without my permission?
No. The send allowlist is empty by default. Agents cannot send any email until you explicitly configure allowed recipients.
Does this store my email credentials?
OAuth tokens are managed by MSAL (Microsoft) and stored in your OS keychain or local config files under ~/.email-agent-mcp/. Agent Email never stores raw passwords.
Can I connect multiple mailboxes?
Yes. You can configure Microsoft 365 and Gmail simultaneously. Read actions default to your primary mailbox; write actions require specifying a mailbox when multiple are configured.
The OpenClaw CLI rejects my config with "Unrecognized key: mcp"
The OpenClaw CLI and macOS app can be different versions. The app (which runs the gateway) may support config keys the CLI doesn't recognize yet. Update the CLI: cd ~/Projects/NemoClaw && npm install openclaw@latest. Alternatively, restart the gateway directly: launchctl kickstart -k gui/501/ai.openclaw.gateway.
The watcher starts but finds zero mailboxes
Mailbox credentials are stored in ~/.email-agent-mcp/tokens/. If this directory is empty, run npx email-agent-mcp or npm run dev:configure to authenticate via OAuth. The watcher will exit with no mailboxes to poll until at least one is configured.
OpenClaw says "Demo mode -- run email-agent-mcp configure to connect"
The MCP server is running but has no real mailbox credentials. Run npx email-agent-mcp to complete the interactive OAuth setup, then restart the OpenClaw gateway so the MCP server reconnects with valid tokens.
Token expired after a week even though I just authenticated
Microsoft refresh tokens typically last 90 days, but your Azure AD tenant may enforce shorter lifetimes. The code uses MSAL with OS keychain persistence (@azure/identity-cache-persistence), which handles silent token refresh automatically. If MSAL reports interaction_required or invalid_grant, re-run npx email-agent-mcp to re-authenticate. Common causes: conditional access policies, MFA re-verification requirements, or admin-configured token lifetime policies.
OpenClaw Telegram bot receives messages but doesn't respond
Verify the Telegram channel is healthy with openclaw status. If the channel shows OK but no responses come back, check that: (1) your Telegram user ID is in channels.telegram.allowFrom in openclaw.json, (2) a binding exists matching channel: "telegram", and (3) the gateway was restarted after config changes. For one-owner bots, use dmPolicy: "allowlist" with explicit allowFrom IDs rather than relying on pairing approvals.
Development
npm ci
npm run build
npm run lint --workspaces --if-present
npm run test:run
npm run check:spec-coverage
See Also
- Safe DOCX Suite -- surgical editing of Word documents with coding agents
- Open Agreements -- fill standard legal templates with coding agents
Privacy
Agent Email runs entirely on your local machine. Email credentials are stored in your OS keychain (MSAL) and local config files. No email content is sent to external servers by Agent Email itself.
