IMAP Model Context Protocol (MCP) Handler

This repository details an MCP server implementation designed to broker access to email services accessible via the Internet Message Access Protocol (IMAP). It empowers intelligent agents (like Claude) to manage user communications effectively.

Core Functionality Summary

This utility grants an assistant the following capabilities concerning electronic mail:

• Scanning mailboxes and executing sophisticated retrieval queries.
• Applying organizational structures (folders, labels, status flags).
• Generating new messages or formulating replies to existing ones.
• Establishing a feedback loop to capture user actions and refine automated processing models (e.g., summarization, routing).
• Facilitating provider-agnostic access across various IMAP endpoints.

Feature Deep Dive

• Secure Credential Exchange: Handles authentication protocols necessary for connecting to diverse IMAP hosts.
• Mailbox Navigation: Enables listing of mailbox structures and enumerating message headers/bodies based on specified criteria.
• Data Inspection: Capability to parse and present message components, including plain text, HTML rendering data, and encapsulated file attachments.
• Message State Modification: Tools for altering message states: relocation, removal, read/unread marking, and flagging.
• Message Construction: Features for authoring outgoing communications, ensuring adherence to standards for threading (In-Reply-To, References) and supporting complex reply formats (e.g., Reply-All). Draft storage integration is also provided.
• Information Retrieval: Implementation of foundational search mechanisms across specified mail stores.
• Adaptive Modeling (Planned): Mechanisms to record and analyze user intervention during message handling to build predictive profiles.

Project Layout

The source code hierarchy is structured for clarity and maintainability:

.
├── examples/              # Sample configuration files
├── imap_mcp/              # Primary Python source modules
│   ├── config.py          # Settings management
│   ├── imap_client.py     # Core network/protocol interaction layer
│   ├── models.py          # Data structure definitions
│   ├── resources.py       # MCP resource endpoint definitions
│   ├── server.py          # The main process listener
│   └── tools.py           # Agent-callable functions
├── tests/                 # Unit and integration test suite
├── INSTALLATION.md        # Step-by-step setup guide
├── pyproject.toml         # Project metadata and dependency definitions
└── README.md              # Documentation root

Initial Setup & Execution

Prerequisites

• Python interpreter version 3.8 or later.
• Active email account configured for IMAP access (Gmail is often used for initial testing).
• Installation of the uv package manager.

Installation Sequence

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

2. Clone and set up the environment: bash git clone https://github.com/non-dirty/imap-mcp.git cd imap-mcp uv venv source .venv/bin/activate uv pip install -e ".[dev]"

Configuring Google Mail Access

1. Duplicate the sample configuration file: bash cp config.sample.yaml config.yaml

2. Generate OAuth2 credentials via the Google Cloud Console:

   • Establish or select a project.
   • Activate the Gmail API.
   • Generate OAuth 2.0 Client IDs (select 'Desktop App' type).
   • Download the resulting credentials.json configuration.

3. Populate config.yaml with the necessary connection and token data: yaml imap: host: imap.gmail.com port: 993 username: primary-address@gmail.com use_ssl: true oauth2: client_id: YOUR_CLIENT_ID_FROM_GCP client_secret: YOUR_CLIENT_SECRET_FROM_GCP refresh_token: YOUR_PERSISTENT_REFRESH_TOKEN

Operational Examples

Fetching Messages from Primary Mailbox

To retrieve the ten most recent messages from the primary folder:

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

Command line arguments include --folder (default: INBOX) and --limit (default: 10).

Launching the MCP Service

Start the main server process:

uv run imap_mcp.server --config config.yaml

For debugging with enhanced logging:

uv run imap_mcp.server --dev

Token Lifecycle Management

To renew an expired OAuth2 access token:

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

To initiate the full token acquisition workflow:

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

Project Maintenance

Development Environment Setup

# Create and activate environment
python -m venv venv
source venv/bin/activate

# Install packages
pip install -e ".[dev]"

Testing

Execute the automated test suite:

pytest

Security Best Practices

Since this utility accesses sensitive mailbox contents, robust security is paramount:

• Prefer utilizing environment variables or dedicated vault systems for storing sensitive credentials over plaintext configuration files.
• Employ application-specific passwords provided by the mail host instead of main account passwords.
• Restrict the scope of IMAP permissions granted to this application where possible.
• Periodically audit the authorization levels conferred upon this service.

Development Timeline

• [x] Initial project scaffolding and version control setup.
• [x] Foundational IMAP protocol linkage.
• [x] Implementation of core email data structures.
• [x] Development of MCP tool endpoints for email.
• [x] Functionality for responding to and saving drafts.
• [ ] Implementation of persistent user interaction modeling.
• [ ] Expansion of query capabilities (advanced search syntax).
• [ ] Support for managing credentials across multiple mail accounts.
• [ ] Hardening integrations for popular providers beyond initial testing.

Collaboration

We welcome external contributions. Refer to [CONTRIBUTING.md] for submission standards.

Licensing

Distributed under the terms of the MIT License (see [LICENSE] file).

Attributions

This project stands on the foundations laid by:

• The Model Context Protocol specification.
• Anthropic's development of large language models.
• Various open-source Python libraries facilitating robust network communication.