Finomosec/imap-mcp-server

IMAP MCP Server

A Model Context Protocol (MCP) server that provides IMAP email functionality with comprehensive email management capabilities. The server uses YAML configuration for IMAP connection settings.

Features

• Automatic IMAP connection using YAML configuration with TLS encryption support
• Load emails with advanced filtering:
  • Filter by sender email address
  • Filter by folder (INBOX, Sent, etc.)
  • Filter by read/unread status
  • Filter emails with/without attachments
  • Pagination support with configurable page size
• Download attachments (all or specific ones)
• Move emails between folders

Installation

npm install

Configuration

Copy config.example.yaml to config.yaml and update with your IMAP settings:

cp config.example.yaml config.yaml

Then edit config.yaml:

imap:
  host: imap.gmail.com
  port: 993
  username: your-email@gmail.com
  password: your-app-password
  use_ssl: true

Required fields:

• host: IMAP server hostname
• username: Email username
• password: Email password

Optional fields:

• port: IMAP server port (default: 993)
• use_ssl: Use SSL/TLS encryption (default: true)

Usage

The server runs on stdio and communicates via the Model Context Protocol. You can specify a custom config file path:

# Use default config.yaml
node src/server.js

# Use custom config file
node src/server.js /path/to/your/config.yaml

Available Tools

1. load_emails

Load emails with various filtering options.

Parameters:

• folder (optional): Folder name (default: "INBOX")
• sender (optional): Filter by sender email address
• read_status (optional): "read", "unread", or "all" (default: "all")
• has_attachment (optional): Filter emails with attachments (boolean)
• page (optional): Page number, 0-based (default: 0)
• page_size (optional): Number of emails per page (default: 20)

Returns:

• Array of email objects with email_id, sender, subject, date, etc.
• Pagination info: has_more_pages, total_count, page, page_size

2. download_attachments

Download attachments from a specific email.

Parameters:

• email_id (required): Email UID from load_emails
• download_dir (optional): Directory to save attachments. Only specify if you need a custom location. If omitted, uses the first configured allowed path. Relative paths are resolved relative to the first configured allowed path.
• filter (optional): Array of attachment filenames or indices to download. Only specify if you want to download specific attachments. If omitted, downloads all attachments.

Move emails to a target folder.

Parameters:

• email_ids (required): Array of email UIDs to move
• target_folder (required): Target folder name

Example Usage

1. Load emails with filters:

{
  "tool": "load_emails",
  "arguments": {
    "sender": "important@company.com",
    "has_attachment": true,
    "page_size": 10
  }
}

2. Download all attachments from an email (uses first configured directory):

{
  "tool": "download_attachments",
  "arguments": {
    "email_id": 12345
  }
}

3. Download specific attachments by filename (to first configured directory):

{
  "tool": "download_attachments",
  "arguments": {
    "email_id": 12345,
    "filter": ["document.pdf", "image.jpg"]
  }
}

4. Download specific attachments by index to custom directory:

{
  "tool": "download_attachments",
  "arguments": {
    "email_id": 12345,
    "filter": [0, 2],
    "download_dir": "/home/user/downloads/email_attachments"
  }
}

5. Download all attachments to a subdirectory (relative to first configured path):

{
  "tool": "download_attachments",
  "arguments": {
    "email_id": 12345,
    "download_dir": "important_emails"
  }
}

6. Move emails to a folder:

{
  "tool": "move_emails",
  "arguments": {
    "email_ids": [12345, 12346],
    "target_folder": "Processed"
  }
}

Configuration

The server uses YAML configuration files. For Gmail, you'll need to:

1. Enable 2-factor authentication
2. Generate an App Password
3. Use imap.gmail.com as the host in your config.yaml

Security Notes

• The server supports TLS encryption by default
• Credentials are stored in the YAML config file - keep it secure

MCP Integration

To integrate this IMAP server with MCP clients (like Claude Desktop), add the following to your mcp.json configuration file:

{
  "mcpServers": {
    "imap-server": {
      "command": "node",
      "args": ["/path/to/your/imap-mcp-server/src/server.js"],
      "env": {}
    }
  }
}

Custom Config File Path

If you want to use a custom config file location:

{
  "mcpServers": {
    "imap-server": {
      "command": "node",
      "args": [
        "/path/to/your/imap-mcp-server/src/server.js",
        "/path/to/your/custom-config.yaml"
      ],
      "env": {}
    }
  }
}

Claude Desktop Integration

For Claude Desktop specifically, the mcp.json file should be located at:

macOS:

~/Library/Application Support/Claude/mcp.json

Windows:

%APPDATA%\Claude\mcp.json

Linux:

~/.config/Claude/mcp.json

After adding the configuration, restart Claude Desktop to load the IMAP server. You should then be able to use email-related commands directly in your conversations with Claude.