ClaudePost: NLP-Driven Electronic Mail Orchestration System

This Model Context Protocol (MCP) endpoint establishes a streamlined conduit for email lifecycle governance, leveraging the conversational intelligence of the Claude AI. Users can issue directives in plain language to manage their inbox, covering secure sending, thorough reading, and precise searching capabilities. The underlying infrastructure also furnishes aggregated daily performance statistics regarding message traffic.

Core Capabilities & Demonstrations

Information Retrieval and Review

• 🔍 Execute searches against archived mail based on temporal parameters and specific textual identifiers.
• 📊 Access aggregated metrics detailing daily message volume.
• 📖 Fetch complete message bodies, maintaining conversational context via threading.

Message Authoring and Dispatch

• 📤 Transmit outgoing correspondence, supporting the inclusion of carbon copy (CC) addressees.
• 🛡️ All transmission and reception operations are fortified using Transport Layer Security (TLS).

System Requirements

• Execution environment requires Python version 3.12 or newer.
• Access to a standard electronic mail service (e.g., Gmail, or comparable IMAP/SMTP provider).
• For Gmail configurations:
• Mandatory enablement of Two-Factor Authentication (2FA).
• Generation and secure storage of an Application-Specific Credential.
• Availability of the Claude Desktop client application.

Deployment Procedure

1. Initialize the utility manager (uv):

bash # Unix-like systems curl -LsSf https://astral.sh/uv/install.sh | sh

# Terminal restart is required for path updates

1. Obtain the source repository and configure the environment:

bash # Clone the project source code git clone https://github.com/ZilongXue/claude-post.git cd claude-post

# Establish and activate the isolated Python runtime space uv venv source .venv/bin/activate # Windows users: .venv\Scripts\activate

# Install project dependencies in editable mode uv pip install -e .

1. Establish the configuration file named .env in the root directory:

env EMAIL_ADDRESS=your.primary.mailbox@service.com EMAIL_PASSWORD=your-generated-application-secret IMAP_SERVER=imap.gmail.com SMTP_SERVER=smtp.gmail.com SMTP_PORT=587

1. Configure the Claude Desktop Application for MCP Integration:

Ensure Claude Desktop is current. Locate or create the configuration file:

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

# Creation command if missing mkdir -p ~/Library/Application\ Support/Claude touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

Insert the following JSON structure into claude_desktop_config.json:

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

Crucially, substitute /Users/username and /path/to/claude-post with the absolute paths specific to your system. The integration takes effect only after restarting the Claude Desktop client.

Server Activation and Operation

Server management is intrinsically linked to the Claude Desktop process:

• Activation occurs automatically upon Claude launch, provided the configuration is accurate.
• Manual server initiation or termination is unnecessary.
• Closing the Claude application ceases server operation.

Interaction via Claude Interface

Utilize conversational instructions to manipulate electronic correspondence. Illustrative commands include:

Querying the Mail Archive

• "Retrieve all messages from the preceding seven days."
• "Isolate correspondence bearing 'project update' in the subject line."
• "Search messages sent by recruiting@linkedin.com between January 1st, 2024, and January 7th, 2024."
• "Display my transmitted items from the last calendar month."

Content Examination

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

Traffic Summarization

• "Report the message count received today."
• "Generate a visualization of daily received message volume for the past week."

Message Generation

• "Initiate an email composition addressed to john@example.com."
• "Dispatch a notification confirming the team meeting details to team@company.com."

Security Precaution: For all sending operations, Claude mandates a final confirmation review of the message payload before actual dispatch.

Directory Layout Reference

claude-post/ ├── pyproject.toml ├── README.md ├── LICENSE ├── .env # Sensitive credentials (excluded from version control) ├── .python-version # Defines required Python version └── src/ └── email_client/ ├── init.py ├── main.py └── server.py # Primary service logic implementation

Security Advisories

• Always employ application-specific passwords instead of primary account credentials.
• Gmail Users must adhere to the following protocol:
• Activate Two-Step Verification on the Google Account.
• Generate a unique App Password for this utility.
• Securely input this App Password into the .env file.

Diagnostic Logging

Comprehensive operational data, including error traces, is systematically recorded within the email_client.log file for troubleshooting purposes.

Licensing Status

This project is distributed under the terms of the MIT License (see LICENSE file).