# mcp-email

A minimal MCP server for reading, searching, managing, and sending email over
IMAP and SMTP. Version 0.1 targets Gmail, while connection settings remain
configurable through environment variables.

## Features

- Connect to and health-check an IMAP account
- List folders and recent inbox messages
- Read plain-text and HTML email bodies
- Search by unread status, subject, sender, and date
- Send plain-text or HTML email with optional CC and BCC
- Mark messages read or unread and permanently delete messages
- List attachment filenames
- Return a cleaned email body as a basic summary

## Setup

Python 3.12 or newer is required.

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

Copy `.env.example` to `.env` and fill in your account details. For Gmail,
enable IMAP and use a Google App Password instead of your account password.
Never commit `.env`.

```env
EMAIL_PROVIDER=gmail
EMAIL_ADDRESS=example@gmail.com
EMAIL_SECRET=your-google-app-password
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
```

## Run

```bash
python server.py
```

Example MCP client configuration:

```json
{
  "mcpServers": {
    "email": {
      "command": "python",
      "args": [
        "C:/Users/your-user/Documents/GitHub/mcp-email/server.py"
      ]
    }
  }
}
```

## Tools

- `connect()`
- `health()`
- `list_folders()`
- `latest_emails(limit=5)`
- `read_email(message_id)`
- `search_emails(unread=False, subject=None, sender=None, since=None, before=None, limit=50)`
- `send_email(to, subject, body, cc=None, bcc=None, html=False)`
- `mark_read(message_id)`
- `mark_unread(message_id)`
- `delete_email(message_id)`
- `list_attachments(message_id)`
- `summarize_email(message_id)`

`delete_email` expunges the selected message immediately and cannot be undone.