home / mcp / mcp email server

MCP Email Server

Unified MCP server for Gmail and IMAP with cross-account search, secure storage, and automated token management.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "kentaroh7777-mcp-email-server": {
      "url": "http://localhost:3456/mcp",
      "headers": {
        "GMAIL_CLIENT_ID": "your-gmail-client-id",
        "GMAIL_REDIRECT_URI": "urn:ietf:wg:oauth:2.0:oob",
        "GMAIL_CLIENT_SECRET": "your-gmail-client-secret",
        "EMAIL_ENCRYPTION_KEY": "your-unique-32-character-encryption-key",
        "IMAP_TLS_accountname": "true",
        "IMAP_HOST_accountname": "mail.example.com",
        "IMAP_PORT_accountname": "993",
        "IMAP_USER_accountname": "[email protected]",
        "IMAP_PASSWORD_accountname": "encrypted-password-here",
        "GMAIL_REFRESH_TOKEN_accountname": "ya29.Gl…"
      }
    }
  }
}

You operate a unified MCP server that manages Gmail OAuth2/API access and IMAP accounts from a single, coherent interface. It enables cross-account searches, account management, and secure handling of credentials while providing robust error handling and automatic token management.

How to use

You interact with the MCP Email Server through a client that speaks the MCP protocol. You can list configured accounts, test connections, and perform common email actions across all Gmail and IMAP accounts. Use the unified interface to run cross-account searches, fetch email details, archive messages, or send emails from any configured account. The server automatically detects account types (Gmail vs IMAP) and routes requests to the appropriate handler, while keeping credentials secure and encrypted where applicable.

How to install

Follow these concrete steps to set up the MCP Email Server on your machine. Ensure you have Node.js and a supported shell available before starting.

# 1. Clone the project repository
git clone <repository-url>
cd mcp-email-server

# 2. Install dependencies
npm install

# 3. Copy and edit environment configuration
cp .env.example .env
nano .env

Additional sections

Configuration and setup details are provided below to help you securely run Gmail and IMAP accounts through the MCP Email Server. Follow the steps to enable OAuth2 for Gmail, configure IMAP connections, and prepare encryption for IMAP passwords.

Security and credentials are designed to minimize risk. All IMAP passwords are encrypted with AES-256-GCM, and Gmail access uses rotating OAuth2 refresh tokens to avoid storing plain credentials.

Key environment variables you will configure include encryption keys, Gmail OAuth credentials, and IMAP connection settings. You will provide an encryption key for password storage and credentials for Gmail and IMAP accounts.

To start the server and verify health, you will use the provided server management scripts to launch, monitor, and test the MCP Email Server.

# Example: start the server and check status
./scripts/server.sh start
./scripts/server.sh status
./scripts/server.sh health

Available tools

list_emails

Retrieve emails from a specified account with automatic type detection between Gmail and IMAP accounts.

search_emails

Search emails in a specific account with automatic type detection between Gmail and IMAP accounts.

search_all_emails

Cross-account search across all Gmail and IMAP accounts.

get_email_detail

Fetch detailed information for a specific email in a given account.

archive_email

Archive an email in a specified account and optionally remove unread status.

send_email

Send an email from a specified account, with optional CC and BCC and attachments.

list_accounts

List configured email accounts with their status.

test_connection

Test connectivity to a particular account.

get_account_stats

Retrieve comprehensive statistics for all accounts.