IMAP Workflows MCP server

The IMAP MCP server enables AI assistants to interact with email systems, allowing them to check, process, and manage emails while learning user preferences over time. It works with Claude or any other MCP-compatible assistant to transform them into intelligent email assistants.

Installation Requirements

Prerequisites

• Python 3.8 or higher
• An IMAP-enabled email account (Gmail recommended)
• uv for package management and running Python scripts

Setting Up the Server

1. Install uv if you haven't already:

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

2. Clone and install the package:

   git clone https://github.com/non-dirty/imap-mcp.git
   cd imap-mcp
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install -e ".[dev]"
   

Gmail Configuration

1. Create a configuration file:

   cp config.sample.yaml config.yaml
   

2. Set up Gmail OAuth2 credentials:

   • Go to Google Cloud Console
   • Create a new project or select an existing one
   • Enable the Gmail API
   • Create OAuth2 credentials (Desktop Application type)
   • Download the client configuration

3. Update your config.yaml with Gmail settings:

   imap:
     host: imap.gmail.com
     port: 993
     username: [email protected]
     use_ssl: true
     oauth2:
       client_id: YOUR_CLIENT_ID
       client_secret: YOUR_CLIENT_SECRET
       refresh_token: YOUR_REFRESH_TOKEN
   

Using the IMAP MCP Server

Managing Email

To list emails in your inbox:

uv run list_inbox.py --config config.yaml --folder INBOX --limit 10

Available options:

• --folder: Specify which folder to check (default: INBOX)
• --limit: Maximum number of emails to display (default: 10)
• --verbose: Enable detailed logging output

Running the MCP Server

Start the IMAP MCP server with:

uv run imap_mcp.server --config config.yaml

For development mode with debugging:

uv run imap_mcp.server --dev

OAuth2 Token Management

To refresh your OAuth2 token:

uv run imap_mcp.auth_setup refresh-token --config config.yaml

To generate a new OAuth2 token:

uv run imap_mcp.auth_setup generate-token --config config.yaml

Security Considerations

Since this MCP server requires access to your email account containing sensitive information:

• Store email credentials securely using environment variables or secure credential storage
• Consider using app-specific passwords instead of your main account password
• Limit folder access to only what's necessary for your use case
• Regularly review the permissions granted to the server in your email provider's settings

Features

The server provides these key capabilities:

Email Management

• Browse and search emails across folders
• Move, delete, mark as read/unread, and flag messages
• Read message contents including text, HTML, and attachments

Email Composition

• Draft and save replies with proper formatting
• Support for plain text and HTML replies
• Reply-all functionality with CC support
• Proper threading with In-Reply-To and References headers
• Save drafts to appropriate folders

Advanced Features

• Email organization (moving, tagging, marking)
• Automated email summarization and categorization
• Support for multiple IMAP providers

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 "imap-mcp" '{"command":"uv","args":["run","imap_mcp.server","--config","config.yaml"]}'

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": {
        "imap-mcp": {
            "command": "uv",
            "args": [
                "run",
                "imap_mcp.server",
                "--config",
                "config.yaml"
            ]
        }
    }
}

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": {
        "imap-mcp": {
            "command": "uv",
            "args": [
                "run",
                "imap_mcp.server",
                "--config",
                "config.yaml"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect