@wraps.dev/mcp gives AI agents access to your AWS SES sending history, delivery events, domain status, and suppression list — and, optionally, the ability to send email. It runs locally over stdio; your AWS credentials never leave your machine.
Before you begin, make sure you have:
wraps email init)The server exposes six tools. Only send_email writes anything, and it stays disabled until you opt in.
| Tool | Description | Access |
|---|---|---|
| list_recent_sends | List recent sends from your email history | read |
| get_email_event_log | Full delivery event log for a message (Send, Delivery, Bounce, Complaint, Open, Click) | read |
| verify_domain_status | Verification and DKIM status of a sending domain | read |
| list_suppressions | Addresses on your SES suppression list, filterable by BOUNCE or COMPLAINT | read |
| send_email | Send a transactional email via your SES account (requires WRAPS_WRITE_ENABLED=true) | write |
| check_send_status | Poll the outcome of a pending_approval send by approvalId (enforced mode only) | read |
Add to .mcp.json in your project root. Claude Code inherits your shell's AWS environment, so no extra env config is needed if your credentials are already set.
{ "mcpServers": { "wraps": { "command": "npx", "args": ["-y", "@wraps.dev/mcp"] } }}GUI clients don't inherit your shell environment, so pass the region and profile explicitly. For Claude Desktop the file is ~/Library/Application Support/Claude/claude_desktop_config.json; for Cursor it's .cursor/mcp.json.
{ "mcpServers": { "wraps": { "command": "npx", "args": ["-y", "@wraps.dev/mcp"], "env": { "AWS_REGION": "us-east-1", "AWS_PROFILE": "your-aws-profile" } } }}All configuration is via environment variables.
| Variable | Required | Default | Description |
|---|---|---|---|
| AWS_REGION | Yes | — | AWS region where your Wraps stack is deployed |
| WRAPS_HISTORY_TABLE_NAME | No | wraps-email-history | DynamoDB table name for email history |
| WRAPS_ACCOUNT_ID | No | auto-detected via STS | Your AWS account ID (skips the STS call if set) |
| WRAPS_WRITE_ENABLED | No | false | Set to true to enable send_email |
| WRAPS_FROM_EMAIL | No | — | Default from address for send_email |
| WRAPS_CONFIGURATION_SET | No | — | SES configuration set applied to sends (enables open/click tracking) |
send_email is disabled by default. Set WRAPS_WRITE_ENABLED=true to enable it. The from address must belong to a domain verified in your SES account.
{ "mcpServers": { "wraps": { "command": "npx", "args": ["-y", "@wraps.dev/mcp"], "env": { "AWS_REGION": "us-east-1", "WRAPS_WRITE_ENABLED": "true", "WRAPS_FROM_EMAIL": "you@yourdomain.com", "WRAPS_ALLOWED_RECIPIENT_DOMAINS": "yourcompany.com" } } }}No allowlist means no limits
Running with WRAPS_WRITE_ENABLED=true and no allowlist gives the agent unrestricted send capability to any address your SES account can reach. Set the guardrails below.
When write mode is enabled, use these variables to restrict the agent's sending scope. A recipient is allowed if it matches either the address list or the domain list.
| Variable | Default | Description |
|---|---|---|
| WRAPS_ALLOWED_RECIPIENTS | — (no restriction) | Comma-separated exact addresses the agent may send to. If set, any address not in this list (or the domains list) is rejected. |
| WRAPS_ALLOWED_RECIPIENT_DOMAINS | — (no restriction) | Comma-separated domains the agent may send to. Matching is exact: example.com allows user@example.com but not subdomains — list each subdomain explicitly. |
| WRAPS_MAX_RECIPIENTS | 50 | Maximum number of recipients per send_email call. |
| WRAPS_ALLOW_FROM_OVERRIDE | false | Set to true to let the agent supply a from address that differs from WRAPS_FROM_EMAIL. When false, a mismatched from is rejected. |
For agents provisioned via wraps email agent create, the MCP server runs in enforced mode. The agent's AWS credential can only invoke an enforcer Lambda in your account — never SES directly. Kill-switch, recipient allowlist, and hourly/daily caps are decided by that Lambda, so the local guardrails above don't apply.
Enforced mode activates when both WRAPS_AGENT_ID and WRAPS_AGENT_ENFORCER_ARN are set. send_email then returns a structured disposition instead of an error for policy outcomes:
sent — delivered, with a messageIdpending_approval — an operator must approve; poll check_send_status with the returned approvalIdblocked — refused by policy (kill-switch, allowlist, or caps), with a reasonOne recipient per send
Enforced mode accepts a single recipient per call. Pass one address (or a one-element array); larger arrays are rejected — send one email per recipient.
Deploy SES and wire a typed send-email tool into your agent framework.
View QuickstartEvery method, option, and response shape in @wraps.dev/email.
View SDK Docs