ClaudePost

What is ClaudePost?

ClaudePost is a Model Context Protocol (MCP) server that integrates with Claude Desktop to provide a seamless email management interface. It allows users to interact with their emails (search, read, compose, send) using natural language conversations directly within Claude.

How to use ClaudePost?

To use ClaudePost, you need Python 3.12+, a Gmail account (or other email provider), and the Claude Desktop application. Setup involves cloning the repository, installing dependencies with uv, configuring a .env file with your email credentials (using an app-specific password for Gmail for security), and finally, configuring Claude Desktop by adding a specific mcpServers entry in its claude_desktop_config.json file. Once configured, the server runs automatically when Claude Desktop is launched, and you can interact with your emails through natural language commands within Claude.

Key Features of ClaudePost

Email Search and Reading

• Search emails by date range and keywords.
• View daily email statistics.
• Read full email content with threading support.

Email Composition and Sending

• Send emails with CC recipients support.
• Secure email handling with TLS.

Use Cases of ClaudePost

ClaudePost is ideal for individuals who want to manage their emails efficiently using natural language. Specific use cases include:

• Quick Email Search: "Show me emails from last week" or "Find emails with subject containing 'meeting'."
• Reading Specific Emails: "Show me the content of email #12345" or "What's the full message of the last email from HR?"
• Email Statistics: "How many emails did I receive today?" or "Show me daily email counts for the past week."
• Composing and Sending Emails: "I want to send an email to john@example.com" or "Send a meeting confirmation to team@company.com."

FAQ about ClaudePost

Q: What are the prerequisites for using ClaudePost? A: Python 3.12 or higher, a Gmail account (or other email provider), and the Claude Desktop application. For Gmail, two-factor authentication and an app-specific password are required.

Q: How does ClaudePost handle security? A: It emphasizes using app-specific passwords instead of your main account password, especially for Gmail users, and handles email securely with TLS.

Q: Do I need to manually run the ClaudePost server? A: No, the server runs automatically through Claude Desktop. It starts when Claude launches and stops when Claude is closed.

Q: Can I send emails directly without confirmation? A: For security reasons, Claude will always show you the email details for confirmation before actually sending an email.

Q: Where can I find logs for debugging? A: The application logs detailed information to email_client.log for debugging and error messages.

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

• 📧 Search emails by date range and keywords
• 📅 View daily email statistics
• 📝 Read full email content with threading support

Email Composition and Sending

• ✉️ 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 generated
• Claude Desktop application

Setup

1. Install uv:

   # 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:

   # 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:

   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. If you already have Claude for Desktop, make sure it's updated to the latest version.

   Open your Claude Desktop configuration file:

   # 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:

   {
     "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.