IMAP MCP Server for AI Assistants

Overview

This MCP (Model Context Protocol) server exposes IMAP operations as callable tools so AI assistants can access and manage email programmatically. It is implemented in TypeScript and designed to run as an MCP-compatible subprocess, presenting IMAP functionality (currently drafting) as tool endpoints that assistants such as Claude can call during workflows.

You can use the server to create and save draft messages directly on an IMAP account, enabling assistants to prepare emails for review or automation pipelines without requiring direct mailbox credentials in the assistant. The server is lightweight and intended to be added to an MCP server list or launched as a standalone process that reads IMAP credentials from environment variables.

Source code and issues: https://github.com/dominik1001/imap-mcp

Features

• Create email drafts and save them to the IMAP server’s Drafts folder
• Compatible with any IMAP-compliant server (Gmail, Outlook, self-hosted servers)
• Environment-driven configuration for credentials and host settings
• MCP-compatible tool interface so AI assistants can call IMAP operations
• Implemented in TypeScript with shipped type definitions for easier extension

Installation / Configuration

Install and run via npx or compile from TypeScript. Example MCP server registration (snippet of a larger MCP config):

{
  "mcpServers": {
    "imap": {
      "command": "npx",
      "args": ["imap-mcp"],
      "env": {
        "IMAP_HOST": "<IMAP host>",
        "IMAP_PORT": "<IMAP port>",
        "IMAP_USERNAME": "<IMAP username>",
        "IMAP_PASSWORD": "<IMAP password>",
        "IMAP_USE_SSL": "<true or false>"
      }
    }
  }
}

Local development (TypeScript -> JavaScript):

# Install dependencies
npm install

# Compile TypeScript
npx tsc

# Run the built server
node dist/index.js

You can also run directly with npx (if published) or via a package manager script:

npx imap-mcp

Environment variables

Keep credentials out of source control and use secure environment provisioning in production. If using OAuth or tokens, ensure the token is valid for IMAP access and supported by your email provider.

Running the server

• Ensure required environment variables are set.
• Start the server via the CLI or as an MCP subprocess.
• The server listens for MCP tool calls and performs IMAP operations using the provided credentials.

Behavior notes:

• The server attempts to save drafts in common drafts folders (for example “INBOX.Drafts” or “Drafts”) depending on what the IMAP server exposes.
• Errors from the IMAP server are surfaced to the calling assistant/tool consumer as structured responses.

Available Tools

Currently exposed tool:

• create-draft — Creates a draft email and stores it in the IMAP drafts folder.

Parameters (JSON):

Example tool call payload:

{
  "to": "[email protected]",
  "subject": "Meeting Reminder",
  "body": "Don't forget about our meeting tomorrow at 2 PM.",
  "from": "[email protected]"
}

Example response (success):

{
  "status": "ok",
  "folder": "Drafts",
  "uid": 12345,
  "message": "Draft saved successfully"
}

If the server cannot find a drafts mailbox, it will attempt common variations and return an error if none are available.

Use Cases

• Assistant-assisted drafting: An AI assistant composes an email for a user and uses create-draft to save it on the user’s IMAP account for later review and sending from a client.
• Workflow automation: Automated processes generate templated messages (e.g., sales follow-ups) and store them as drafts for a human to verify before sending.
• Integration with CRMs or ticketing: When a CRM action requires a human-crafted response, the system can save prepared drafts into the user’s mailbox to ensure traceability and easy editing.
• Safe credential boundaries: Run the MCP server in a controlled environment so the assistant can request email operations without directly handling raw mailbox credentials in the assistant session.

Extending the server

The project is implemented in TypeScript and provides a clear starting point for adding additional IMAP operations (search, move, fetch messages, etc.). Contributing or extending should follow the existing MCP tool pattern: add a new handler, define parameter schema, and map the handler to IMAP client actions.

For code, issues, and contribution guidelines, see the repository: https://github.com/dominik1001/imap-mcp

License

MIT — see the repository for license details.