Gmail Cleanup & Categorization
kushal45LABSCO SUMMARY
A mailbox, not a mail vendor's API.
Most mail integrations bind you to one provider's SDK and one provider's OAuth dance. This one speaks IMAP and SMTP, so it works against whatever server you already have, and the setup is a five-line file. The cost of that simplicity is that a working password sits on disk in plain text — which is exactly why the Gmail path is documented as an app-specific password you can revoke on its own.
What it is
An MCP server that connects one ordinary mail account over IMAP and SMTP. It runs on your machine, reads its credentials from a local .env file, and talks directly to your provider — Gmail in the worked example, but anything speaking those two protocols will do.
What you get
- Mailbox search by date range and keyword, including the sent folder
- Daily counts of received mail, so "how much came in last week" is one question rather than a scroll
- Full message content with threading, addressed by email ID
- Composing and sending with CC recipients, over TLS
- A confirmation step before anything leaves: the message details are shown back to you first
Requirements
Python 3.12 or higher and uv for the virtual environment; the package is email_client and the launcher command is email-client. A .env file holds EMAIL_ADDRESS, EMAIL_PASSWORD, IMAP_SERVER, SMTP_SERVER and SMTP_PORT. On Gmail that means two-step verification switched on and an app-specific password rather than your account password. Activity is logged to email_client.log.
Setup effort
Build from source — git clone https://github.com/ZilongXue/claude-post.git
USE CASES
01
Finding the thread you only half remember
Search by sender, subject fragment and a date window at once, then open the full text of the one that matches.
02
Seeing how heavy the week was
Ask for daily received counts over a period instead of estimating from the inbox view.
03
Sending a reply without changing windows
Dictate the message and the CC list, read back the details it shows you, then confirm.
BEFORE YOU INSTALL
What to know first
Requires
- uv on PATH
- Python 3.12 or later
- EMAIL_PASSWORD in your environment
- EMAIL_ADDRESS in your environment
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
git clone https://github.com/ZilongXue/claude-post.git
cd claude-post
uv venv
source .venv/bin/activate
uv pip install -e .Create a .env file in the project root with EMAIL_ADDRESS, EMAIL_PASSWORD (a Gmail app-specific password), IMAP_SERVER=imap.gmail.com, SMTP_SERVER=smtp.gmail.com and SMTP_PORT=587
In the configuration below, /Users/<YOUR_USERNAME> and <YOUR_PATH_TO_CLAUDE_POST> are your own paths
MCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"email": {
"command": "/Users/<YOUR_USERNAME>/.local/bin/uv",
"args": [
"--directory",
"<YOUR_PATH_TO_CLAUDE_POST>/src/email_client",
"run",
"email-client"
]
}
}
}The configuration does not set EMAIL_ADDRESS or EMAIL_PASSWORD; they go in the .env file in the project root (see the steps). For Gmail, turn on two-factor authentication and generate an app-specific password first.
