Email MCP Server

An MCP (Model Context Protocol) server that exposes common email operations as tools for LLM clients like Claude. Supports multiple named email accounts (e.g., work + Gmail) from a single server instance.

For more information, see my blog.

Example prompts

"Find the tax emails from my tax lawyers for 2025, and check the content and attachments to fully understand what documentation I need to provide. Please provide an action plan to get that documentation."

"Please help triage the emails in my inboxes. As per usual, flag anything that is actionable. Don't hesitate to read emails that you are uncertain about. For anything actionable, provide an action plan. For anything non-actionable, file according to the folder layout."

WARNING: This server performs real operations on your mailbox, for example moving emails around. By default it will not allow deletions and directly sending emails (this can be changed in the MCP config). The author assumes no responsibility for any loss of data or unintended consequences resulting from the use of this MCP server. Use at your own risk.

NOTE: That said, the author has been using this daily for weeks without issues.

Features / Tools

All tools (except listAccounts) require an account parameter — the name of the account to operate on (e.g., work, gmail).

Quick Start

The fastest way to get started is to download a pre-built release from the Releases page. Two options are available:

Option A: Native Binary (recommended)

No Java installation required. Download the binary for your platform:

On Linux, make the binary executable: chmod +x mcp-email-server-*-linux-*

Option B: Uber-jar

Runs on any platform with Java 21+ installed. Download mcp-email-server-<version>-runner.jar.

Then configure your MCP client (see Claude Desktop or Claude Code below).

Configuration

All credentials are passed via environment variables — nothing sensitive goes in source control. The LLM never sees these variables — it only sees tool names/descriptions and the text your tools return.

Accounts are defined by convention: EMAIL_ACCOUNTS_<NAME>_IMAP_* and EMAIL_ACCOUNTS_<NAME>_SMTP_*, where <NAME> is the account name in uppercase.

Per-account variables

For Gmail, create an App Password.

You can define as many accounts as needed. For example, to add a work and gmail account, set environment variables for both EMAIL_ACCOUNTS_WORK_* and EMAIL_ACCOUNTS_GMAIL_*.

Safety flags — opt-in for irreversible actions

Permanent and outbound operations are opt-in for safety. By default the destructive/outbound tools are disabled and return an explanatory error so the LLM can tell the user what's happening and fall back to a safer alternative (moveEmail to a Trash folder, or saveDraft for the user to send manually).

Equivalent system properties: -Demail.allow-deletion=true and -Demail.allow-sending=true. Restart the server after changing them.

Enabling permanent deletion

When EMAIL_ALLOW_DELETION is unset (or false), deleteEmail is still listed (so the LLM can discover it and explain the limitation), but every invocation is rejected before any IMAP call is made. Use moveEmail to a Trash folder as the safe alternative.

Enabling outbound sending

When EMAIL_ALLOW_SENDING is unset (or false), the four outbound tools above all return an explanatory error and do nothing. saveDraft is unaffected — it only writes to the IMAP Drafts folder, so the LLM can still compose messages for the user to review and send manually from their mail client. This is the recommended default workflow even when sending is enabled.

Setting up with Claude Desktop

1. Download a release (see Quick Start) or build from source.

2. Edit the Claude Desktop config file claude_desktop_config.json. On Windows it is located at C:\Users\<UserName>\AppData\Roaming\Claude\claude_desktop_config.json. On macOS it is at ~/Library/Application Support/Claude/claude_desktop_config.json.

3. Add the email entry to the mcpServers section. Here is an example with two accounts (work and gmail):

Using the native binary (Windows):

{
  "mcpServers": {
    "email": {
      "command": "C:\\Users\\YourName\\path\\to\\mcp-email-server-windows-x86_64.exe",
      "args": [
        "-Dquarkus.mcp.server.stdio.enabled=true",
        "-Dquarkus.config.locations=.",
        "-Duser.dir=C:\\Users\\YourName\\claude"
      ],
      "env": {
        "EMAIL_ACCOUNTS_WORK_IMAP_HOST": "imap.example.com",
        "EMAIL_ACCOUNTS_WORK_IMAP_USERNAME": "user@example.com",
        "EMAIL_ACCOUNTS_WORK_IMAP_PASSWORD": "your-app-password",
        "EMAIL_ACCOUNTS_WORK_SMTP_HOST": "smtp.example.com",
        "EMAIL_ACCOUNTS_WORK_SMTP_USERNAME": "user@example.com",
        "EMAIL_ACCOUNTS_WORK_SMTP_PASSWORD": "your-app-password",
        "EMAIL_ACCOUNTS_GMAIL_IMAP_HOST": "imap.gmail.com",
        "EMAIL_ACCOUNTS_GMAIL_IMAP_USERNAME": "you@gmail.com",
        "EMAIL_ACCOUNTS_GMAIL_IMAP_PASSWORD": "your-gmail-app-password",
        "EMAIL_ACCOUNTS_GMAIL_SMTP_HOST": "smtp.gmail.com",
        "EMAIL_ACCOUNTS_GMAIL_SMTP_USERNAME": "you@gmail.com",
        "EMAIL_ACCOUNTS_GMAIL_SMTP_PASSWORD": "your-gmail-app-password"
      }
    }
  }
}

Using the uber-jar:

{
  "mcpServers": {
    "email": {
      "command": "java",
      "args": [
        "-Dquarkus.mcp.server.stdio.enabled=true",
        "-Dquarkus.config.locations=.",
        "-Duser.dir=C:\\Users\\YourName\\claude",
        "-jar",
        "C:\\Users\\YourName\\path\\to\\mcp-email-server-runner.jar"
      ],
      "env": {
        "EMAIL_ACCOUNTS_WORK_IMAP_HOST": "imap.example.com",
        "EMAIL_ACCOUNTS_WORK_IMAP_USERNAME": "user@example.com",
        "EMAIL_ACCOUNTS_WORK_IMAP_PASSWORD": "your-app-password",
        "EMAIL_ACCOUNTS_WORK_SMTP_HOST": "smtp.example.com",
        "EMAIL_ACCOUNTS_WORK_SMTP_USERNAME": "user@example.com",
        "EMAIL_ACCOUNTS_WORK_SMTP_PASSWORD": "your-app-password",
        "EMAIL_ACCOUNTS_GMAIL_IMAP_HOST": "imap.gmail.com",
        "EMAIL_ACCOUNTS_GMAIL_IMAP_USERNAME": "you@gmail.com",
        "EMAIL_ACCOUNTS_GMAIL_IMAP_PASSWORD": "your-gmail-app-password",
        "EMAIL_ACCOUNTS_GMAIL_SMTP_HOST": "smtp.gmail.com",
        "EMAIL_ACCOUNTS_GMAIL_SMTP_USERNAME": "you@gmail.com",
        "EMAIL_ACCOUNTS_GMAIL_SMTP_PASSWORD": "your-gmail-app-password"
      }
    }
  }
}

4. Restart Claude Desktop. The email tools should appear in the tool list.

Setting up with Claude Code

1. Download a release (see Quick Start) or build from source.

2. Edit ~/.claude.json and add an mcpServers section. Here is an example with two accounts (work and gmail):

Using the native binary (Linux):

{
  "mcpServers": {
    "email": {
      "command": "/path/to/mcp-email-server-linux-x86_64",
      "args": [
        "-Dquarkus.mcp.server.stdio.enabled=true"
      ],
      "env": {
        "EMAIL_ACCOUNTS_WORK_IMAP_HOST": "imap.example.com",
        "EMAIL_ACCOUNTS_WORK_IMAP_USERNAME": "user@example.com",
        "EMAIL_ACCOUNTS_WORK_IMAP_PASSWORD": "your-app-password",
        "EMAIL_ACCOUNTS_WORK_SMTP_HOST": "smtp.example.com",
        "EMAIL_ACCOUNTS_WORK_SMTP_USERNAME": "user@example.com",
        "EMAIL_ACCOUNTS_WORK_SMTP_PASSWORD": "your-app-password",
        "EMAIL_ACCOUNTS_GMAIL_IMAP_HOST": "imap.gmail.com",
        "EMAIL_ACCOUNTS_GMAIL_IMAP_USERNAME": "you@gmail.com",
        "EMAIL_ACCOUNTS_GMAIL_IMAP_PASSWORD": "your-gmail-app-password",
        "EMAIL_ACCOUNTS_GMAIL_SMTP_HOST": "smtp.gmail.com",
        "EMAIL_ACCOUNTS_GMAIL_SMTP_USERNAME": "you@gmail.com",
        "EMAIL_ACCOUNTS_GMAIL_SMTP_PASSWORD": "your-gmail-app-password"
      }
    }
  }
}

Using the uber-jar:

{
  "mcpServers": {
    "email": {
      "command": "java",
      "args": [
        "-Dquarkus.mcp.server.stdio.enabled=true",
        "-jar",
        "/path/to/mcp-email-server-runner.jar"
      ],
      "env": {
        "EMAIL_ACCOUNTS_WORK_IMAP_HOST": "imap.example.com",
        "EMAIL_ACCOUNTS_WORK_IMAP_USERNAME": "user@example.com",
        "EMAIL_ACCOUNTS_WORK_IMAP_PASSWORD": "your-app-password",
        "EMAIL_ACCOUNTS_WORK_SMTP_HOST": "smtp.example.com",
        "EMAIL_ACCOUNTS_WORK_SMTP_USERNAME": "user@example.com",
        "EMAIL_ACCOUNTS_WORK_SMTP_PASSWORD": "your-app-password",
        "EMAIL_ACCOUNTS_GMAIL_IMAP_HOST": "imap.gmail.com",
        "EMAIL_ACCOUNTS_GMAIL_IMAP_USERNAME": "you@gmail.com",
        "EMAIL_ACCOUNTS_GMAIL_IMAP_PASSWORD": "your-gmail-app-password",
        "EMAIL_ACCOUNTS_GMAIL_SMTP_HOST": "smtp.gmail.com",
        "EMAIL_ACCOUNTS_GMAIL_SMTP_USERNAME": "you@gmail.com",
        "EMAIL_ACCOUNTS_GMAIL_SMTP_PASSWORD": "your-gmail-app-password"
      }
    }
  }
}

3. Restart Claude Code (or run /mcp to reconnect). The email tools should appear in the tool list.

Note: Unlike Claude Desktop, Claude Code does not typically need the -Duser.dir and -Dquarkus.config.locations workarounds since it launches the server from a normal working directory.

Building from Source

Only needed if you want to contribute or run a development build.

Uber-jar

Prerequisites: Java 21+ and Maven 3.9+

mvn package

The uber-jar will be at target/mcp-email-server-<version>-runner.jar.

Native image

Prerequisites: GraalVM 25 with native-image, and Maven 3.9+. On Windows, Visual Studio 2022 with the "Desktop development with C++" workload is also required.

mvn package -Dnative -DskipTests

The native binary will be at target/mcp-email-server-<version>-runner (or .exe on Windows).

Troubleshooting

• AccessDeniedException: C:\WINDOWS\system32\config: on Windows, Claude Desktop may launch the server with C:\WINDOWS\system32 as the working directory, causing Quarkus to fail when scanning for config files. The -Duser.dir argument in the example config overrides the working directory, and -Dquarkus.config.locations=. prevents Quarkus from scanning restricted system directories. Point -Duser.dir to any directory your user can write to.
• Server disconnects immediately: make sure -Dquarkus.mcp.server.stdio.enabled=true is in the args before -jar.
• No log output visible: Quarkus logs go to mcp-email-server.log (in the working directory), not to stdout/stderr, to avoid interfering with the STDIO transport. Check that file for errors.
• Authentication errors: for Gmail, you need an App Password, not your regular password. Make sure 2-Step Verification is enabled on your Google account first.
• Build fails (building from source): ensure JAVA_HOME points to JDK 21+. The system java on PATH may differ from what Maven uses.
• "Unknown account" errors: call listAccounts first to see which accounts are configured. Account names are lowercase as defined in the environment variables (e.g., work, gmail).