Email Manager MCP server

The ClaudePost server provides a seamless email management interface through Claude. This integration allows you to handle emails through natural language conversations with Claude, including searching, reading, and sending emails securely, all without leaving your Claude Desktop application.

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

Installation and Setup

Step 1: Install UV Package Manager

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

# Remember to restart your terminal after installation

Step 2: Clone and Configure 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 .

Step 3: Set Up Environment Variables

Create a .env file in the project root with your email credentials:

[email protected]
EMAIL_PASSWORD=your-app-specific-password
IMAP_SERVER=imap.gmail.com
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587

Step 4: Configure Claude Desktop

1. Install Claude for Desktop from claude.ai/download if you haven't already

2. 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

3. Add the MCP server 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.

4. Restart Claude Desktop for the changes to take effect.

Using ClaudePost

The server runs automatically when Claude Desktop launches. Here are some examples of how to interact with your emails using natural language:

Searching Emails

You can use queries like:

• "Show me emails from last week"
• "Find emails with subject containing 'meeting'"
• "Search for emails from [email protected] between 2024-01-01 and 2024-01-07"
• "Search sent emails from last month"

Reading Emails

Request email content with:

• "Show me the content of email #12345"
• "What's the full message of the last email from HR?"

Email Statistics

Get insights about your inbox:

• "How many emails did I receive today?"
• "Show me daily email counts for the past week"

Sending Emails

Compose and send messages:

• "I want to send an email to [email protected]"
• "Send a meeting confirmation to [email protected]"

For security, Claude will always show you the email details for confirmation before actually sending.

Security Considerations

• Always 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 specifically for this application
  3. Use this App Password in your .env file

Troubleshooting

If you encounter issues, check the email_client.log file for detailed information and error messages that can help diagnose problems.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect