WorkMail MCP Server

A Model Context Protocol (MCP) server that connects Claude Desktop to Amazon WorkMail, providing email and calendar access over a secure local stdio transport.

Features

Tool	Description
`list_emails`	List emails from any folder with pagination
`read_email`	Read full email content by ID
`search_emails`	Search emails using AQS query syntax
`send_email`	Send an email (requires explicit confirmation)
`list_calendar_events`	List calendar events in a date range
`get_calendar_event`	Get full event details by ID
`create_calendar_event`	Create a calendar event (requires explicit confirmation)

Security

Credentials are stored in macOS Keychain (hardware-encrypted on Apple Silicon) — never in config files or environment variables
Transport uses stdio (local pipe) — no HTTP server, no open ports
Wire encryption via HTTPS/TLS to the WorkMail EWS endpoint
Input validation on every tool call via Zod schemas
Output sanitization redacts credential values from all responses and error messages
Rate limiting prevents runaway request loops (configurable, default 30/min)
Write protection — send_email and create_calendar_event require a confirm: true parameter

Prerequisites

macOS (uses Keychain for credential storage)
Node.js 20+
Amazon WorkMail account with username/password authentication

Setup

1. Install dependencies

git clone https://github.com/your-username/workmail-mcp-server.git
cd workmail-mcp-server
npm install

2. Configure environment

cp .env.example .env

Edit .env if your WorkMail is in a different region:

WORKMAIL_MCP_EWS_ENDPOINT=https://ews.mail.us-west-2.awsapps.com/EWS/Exchange.asmx

The EWS endpoint follows the pattern https://ews.mail.<region>.awsapps.com/EWS/Exchange.asmx. Common regions: us-east-1, us-west-2, eu-west-1.

3. Store credentials

npm run setup-credentials

This prompts for your WorkMail email and password, stores them in macOS Keychain, and validates the connection.

4. Build

npm run build

5. Register with Claude Desktop

Add the following to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "workmail": {
      "command": "node",
      "args": ["/absolute/path/to/workmail-mcp-server/dist/index.js"]
    }
  }
}

Restart Claude Desktop. The WorkMail server should appear as connected.

Configuration

All settings are optional and have sensible defaults. Set them in .env or as environment variables:

Variable	Default	Description
`WORKMAIL_MCP_EWS_ENDPOINT`	`https://ews.mail.us-west-2.awsapps.com/EWS/Exchange.asmx`	WorkMail EWS endpoint URL
`WORKMAIL_MCP_MAX_EMAILS`	`25`	Max emails returned per request (1-100)
`WORKMAIL_MCP_MAX_CALENDAR_DAYS`	`30`	Max calendar date range in days (1-90)
`WORKMAIL_MCP_RATE_LIMIT`	`30`	Max requests per minute (1-60)
`WORKMAIL_MCP_LOG_LEVEL`	`info`	Log verbosity: `error`, `warn`, `info`, `debug`

Environment variables set in claude_desktop_config.json take precedence over .env.

Usage

Once connected, ask Claude Desktop to interact with your WorkMail:

"List my recent emails"
"Read the email from Sarah about the Q3 report"
"Search my inbox for messages about the deployment"
"What meetings do I have this week?"
"Send an email to team@example.com about the status update"
"Create a meeting for tomorrow at 2pm with Alex"

Development

# Run directly from TypeScript (no build step)
npm run dev

# Rebuild after changes
npm run build

# Re-run credential setup
npm run setup-credentials

Logs are written to stderr in JSON format. To see them while running via Claude Desktop, check the MCP server logs in Claude Desktop's developer tools.

Architecture

Claude Desktop  <──stdio──>  MCP Server (Node.js)
                                  │
                                  ▼
                            EWS Client Layer
                                  │
                                  ▼
                  Amazon WorkMail (Exchange Web Services)

The server uses the EWS protocol at the Exchange2010_SP2 compatibility level, which is the version supported by Amazon WorkMail.

License

MIT