AI-Powered Mail Orchestrator (claude-post)

A Model Context Protocol (MCP) agent designed to furnish an intuitive digital correspondence management environment powered by Claude. This integration facilitates direct manipulation of email archives and composition via natural language dialogue, supporting essential operations like secure transmission, content fetching, and query execution.

Core Capabilities & Demonstrations

Correspondence Retrieval and Review

📧 Execute lookups for messages based on temporal windows and specified keywords.
📅 Present aggregated daily statistics regarding message volume.
📝 Render complete message bodies, respecting established conversation threads.

Message Drafting and Dispatch

✉️ Facilitate outgoing mail construction incorporating specified CC addressees.
🔒 Ensure transactional integrity via Transport Layer Security (TLS) protocols.

Essential Requirements

Python interpreter version 3.12 or newer is mandatory.
Access to a provider account (e.g., Gmail).
If leveraging Gmail:
Two-Step Verification must be active on the account.
An application-specific security credential must be procured.
The Claude Desktop client software.

Deployment Procedure

Install the uv package manager:

bash # Operating systems: MacOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh

# A terminal session restart is required post-installation

Obtain the repository and finalize setup:

bash # Repository acquisition git clone https://github.com/ZilongXue/claude-post.git cd claude-post

# Environment isolation and activation uv venv source .venv/bin/activate # Windows equivalent: .venv\Scripts\activate

# Dependency installation uv pip install -e .

Establish a configuration file named .env in the project's root directory:

env EMAIL_ADDRESS=your.email@gmail.com EMAIL_PASSWORD=your-app-specific-password IMAP_SERVER=imap.gmail.com SMTP_SERVER=smtp.gmail.com SMTP_PORT=587

Configure the Claude Desktop Application Settings:

Ensure the latest Claude for Desktop is installed via this source. Upon confirmation of installation/update, locate and edit the configuration file:

bash # MacOS path example ~/Library/Application Support/Claude/claude_desktop_config.json

# File creation if absent mkdir -p ~/Library/Application\ Support/Claude touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

Inject the following JSON structure into the configuration file:

{ "mcpServers": { "email": { "command": "/Users/username/.local/bin/uv", "args": [ "--directory", "/path/to/claude-post/src/email_client", "run", "email-client" ] } } }

Substitute placeholder paths (/Users/username and /path/to/claude-post) with your actual system directories. Restart Claude Desktop to apply these modifications.

Server Execution Model

The application daemon initializes and operates implicitly via the Claude Desktop environment:

Automatic initiation upon Claude startup, provided configuration is correct.
Zero requirement for manual server upkeep.
Termination of the service occurs concurrently with the closing of the Claude application.

Interaction Via Claude Interface

User interaction is managed entirely through natural language queries directed at the AI agent. Examples include:

Message Querying

"Retrieve all correspondence from the preceding seven days."
"Identify messages whose subject line contains the term 'synopsis'."
"Search for inbound messages from recruiting@linkedin.com between January 1st, 2024, and January 7th, 2024."
"Examine sent items from the previous calendar month."

Content Inspection

"Display the complete text of message identifier 12345."
"What is the full content of the most recent communication from the Human Resources department?"

Volume Metrics

"Provide a count of emails received throughout the current day."
"Chart the daily influx of messages over the last week."

Message Composition

"Initiate an outgoing message addressed to john@example.com."
"Draft and transmit a scheduling confirmation to team@company.com."

Note: For protective measures, the agent mandates explicit user confirmation of all message contents and recipients prior to actual transmission.

Directory Layout

claude-post/ ├── pyproject.toml ├── README.md ├── LICENSE ├── .env # Excluded from version control ├── .python-version # Specification of the required Python interpreter version └── src/ └── email_client/ ├── init.py ├── main.py └── server.py # Primary operational logic resides here

Security Directives

Prioritize the utilization of application-specific credentials over primary account passwords.
Specific guidance for Gmail users:
Activate Two-Step Verification within your Google Account settings.
Generate a dedicated App Password for this service.
Input this App Password into the .env file.

Operational Logging

The system generates comprehensive diagnostic data within the file named email_client.log. Review this file for detailed insights, debugging assistance, or error reporting.