Skip to main content
Glama
Sign In
enesjakozh

IMAP MCP Server

by non-dirty
GitHub
Python
2
  • Linux
  • Apple
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

IMAP MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to check email, process messages, and learn user preferences through interaction.

Overview

This project implements an MCP server that interfaces with IMAP email servers to provide the following capabilities:

  • Email browsing and searching
  • Email organization (moving, tagging, marking)
  • Email composition and replies
  • Interactive email processing and learning user preferences
  • Automated email summarization and categorization
  • Support for multiple IMAP providers

The IMAP MCP server is designed to work with Claude or any other MCP-compatible assistant, allowing them to act as intelligent email assistants that learn your preferences over time.

Features

  • Email Authentication: Secure access to IMAP servers with various authentication methods
  • Email Browsing: List folders and messages with filtering options
  • Email Content: Read message contents including text, HTML, and attachments
  • Email Actions: Move, delete, mark as read/unread, flag messages
  • Email Composition: Draft and save replies to messages 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
  • Search: Basic search capabilities across folders
  • Interaction Patterns: Structured patterns for processing emails and learning preferences (planned)
  • Learning Layer: Record and analyze user decisions to predict future actions (planned)

Current Project Structure

The project is currently organized as follows:

. ├── examples/ # Example configurations │ └── config.yaml.example ├── imap_mcp/ # Source code │ ├── __init__.py │ ├── config.py # Configuration handling │ ├── imap_client.py # IMAP client implementation │ ├── models.py # Data models │ ├── resources.py # MCP resources implementation │ ├── server.py # Main server implementation │ └── tools.py # MCP tools implementation ├── tests/ # Test suite │ ├── __init__.py │ └── test_models.py ├── INSTALLATION.md # Detailed installation guide ├── pyproject.toml # Project configuration └── README.md # This file

Getting Started

Prerequisites

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

Installation

  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 config file:
    cp config.sample.yaml config.yaml
  2. Set up Gmail OAuth2 credentials:
    • Go to Google Cloud Console
    • Create a new project or select existing one
    • Enable the Gmail API
    • Create OAuth2 credentials (Desktop Application type)
    • Download the client configuration
  3. Update config.yaml with your Gmail settings:
    imap: host: imap.gmail.com port: 993 username: your-email@gmail.com use_ssl: true oauth2: client_id: YOUR_CLIENT_ID client_secret: YOUR_CLIENT_SECRET refresh_token: YOUR_REFRESH_TOKEN

Usage

Checking 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
Starting the MCP Server

To start the IMAP MCP server:

uv run imap_mcp.server --config config.yaml

For development mode with debugging:

uv run imap_mcp.server --dev
Managing OAuth2 Tokens

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

Development

Setting Up Development Environment

# Set up virtual environment python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install development dependencies pip install -e ".[dev]"

Running Tests

pytest

Security Considerations

This MCP server requires access to your email account, which contains sensitive personal information. Please be aware of the following security considerations:

  • 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
  • Review the permissions granted to the server in your email provider's settings

Project Roadmap

  • Project initialization and repository setup
  • Basic IMAP integration
  • Email resource implementation
  • Email tool implementation
  • Email reply and draft functionality
  • User preference learning implementation
  • Advanced search capabilities
  • Multi-account support
  • Integration with major email providers

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A Model Context Protocol server that enables AI assistants to access and manage email through IMAP, supporting browsing, searching, reading, and organizing emails while learning user preferences over time.

  1. Overview
    1. Features
      1. Current Project Structure
        1. Getting Started
          1. Prerequisites
          2. Installation
          3. Gmail Configuration
          4. Usage
        2. Development
          1. Setting Up Development Environment
          2. Running Tests
        3. Security Considerations
          1. Project Roadmap
            1. Contributing
              1. License
                1. Acknowledgments

                  Related MCP Servers

                  • MCP Personal Assistant Agent

                    zhangzhongnan928
                    -
                    security
                    F
                    license
                    -
                    quality
                    A versatile Model Context Protocol server that enables AI assistants to manage calendars, track tasks, handle emails, search the web, and control smart home devices.
                    Last updated -
                    2
                    Python
                    • Apple
                    • Linux

                  • Gmail MCP Server

                    zacco16
                    -
                    security
                    F
                    license
                    -
                    quality
                    A Model Context Protocol server that enables AI assistants to interact with Gmail services, supporting email operations, draft management, and calendar functionality through Google API integration.
                    Last updated -
                    TypeScript

                  • Enhanced Gmail MCP Server

                    theposch
                    -
                    security
                    A
                    license
                    -
                    quality
                    A Model Context Protocol server that enables AI assistants like Claude to interact with Gmail through natural language, providing comprehensive email management capabilities including sending, reading, organizing, searching, and managing drafts and labels.
                    Last updated -
                    Python
                    GPL 3.0
                    • Apple

                  • Mailgun MCP Serverofficial

                    mailgun
                    -
                    security
                    A
                    license
                    -
                    quality
                    A Model Context Protocol server implementation that enables AI assistants like Claude Desktop to interact with Mailgun email services, allowing users to send emails and visualize email delivery statistics through natural language.
                    Last updated -
                    6
                    JavaScript
                    Apache 2.0
                    • Apple

                  View all related MCP servers

                  New MCP Servers

                  MCP directory API

                  We provide all the information about MCP servers via our MCP API.

                  curl -X GET 'https://glama.ai/api/mcp/v1/servers/non-dirty/imap-mcp'

                  If you have feedback or need assistance with the MCP directory API, please join our Discord server