Content
# ClaudePost
A Model Context Protocol (MCP) server that provides a seamless email management interface through Claude. This integration allows you to handle emails directly through natural language conversations with Claude, supporting features like searching, reading, and sending emails securely.
## Features & Demo
### Email Search and Reading
<p align="center">
<img src="assets/gif1.gif" width="800"/>
</p>
- 📧 Search emails by date range and keywords
- 📅 View daily email statistics
- 📝 Read full email content with threading support
### Email Composition and Sending
<p align="center">
<img src="assets/gif2.gif" width="800"/>
</p>
- ✉️ Send emails with CC recipients support
- 🔒 Secure email handling with TLS
## Prerequisites
- Python 3.12 or higher
- A Gmail account (or other email provider)
- If using Gmail:
- Two-factor authentication enabled
- [App-specific password](https://support.google.com/mail/answer/185833?hl=en) generated
- Claude Desktop application
## Setup
1. Install uv:
```bash
# MacOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Remember to restart your terminal after installation
```
2. Clone and set up the project:
```bash
# Clone the repository
git clone https://github.com/ZilongXue/claude-post.git
cd claude-post
# Create and activate virtual environment
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
uv pip install -e .
```
3. Create a `.env` file in the project root:
```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
```
4. Configure Claude Desktop:
First, make sure you have Claude for Desktop installed. You can install the latest version [here](https://claude.ai/download). If you already have Claude for Desktop, make sure it's updated to the latest version.
Open your Claude Desktop configuration file:
```bash
# MacOS
~/Library/Application Support/Claude/claude_desktop_config.json
# Create the file if it doesn't exist
mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
Add the following configuration:
```json
{
"mcpServers": {
"email": {
"command": "/Users/username/.local/bin/uv",
"args": [
"--directory",
"/path/to/claude-post/src/email_client",
"run",
"email-client"
]
}
}
}
```
Replace `/Users/username` and `/path/to/claude-post` with your actual paths.
After updating the configuration, restart Claude Desktop for the changes to take effect.
## Running the Server
The server runs automatically through Claude Desktop:
- The server will start when Claude launches if configured correctly
- No manual server management needed
- Server stops when Claude is closed
## Usage Through Claude
You can interact with your emails using natural language commands. Here are some examples:
### Search Emails
- "Show me emails from last week"
- "Find emails with subject containing 'meeting'"
- "Search for emails from recruiting@linkedin.com between 2024-01-01 and 2024-01-07"
- "Search sent emails from last month"
### Read Email Content
- "Show me the content of email #12345"
- "What's the full message of the last email from HR?"
### Email Statistics
- "How many emails did I receive today?"
- "Show me daily email counts for the past week"
### Send Emails
- "I want to send an email to john@example.com"
- "Send a meeting confirmation to team@company.com"
Note: For security reasons, Claude will always show you the email details for confirmation before actually sending.
## Project Structure
```
claude-post/
├── pyproject.toml
├── README.md
├── LICENSE
├── .env # Not included in repo
├── .python-version # Python version specification
└── src/
└── email_client/
├── __init__.py
├── __main__.py
└── server.py # Main implementation
```
## Security Notes
- Use app-specific passwords instead of your main account password
- For Gmail users:
1. Enable 2-Step Verification in your Google Account
2. Generate an App Password for this application
3. Use the App Password in your `.env` file
## Logging
The application logs detailed information to `email_client.log`. Check this file for debugging information and error messages.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
