IMAP MCP Server
Allows management of email accounts on Namecheap Private Email, including listing, reading, searching, sending, and organizing emails via IMAP/SMTP.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
IMAP MCP Server
Multi-account IMAP/SMTP MCP server for Claude. Connects multiple email accounts via a single deployment using FastMCP.
Setup
1. Install dependencies
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt2. Configure accounts
cp .env.example .env
# Edit .env with your IMAP/SMTP credentialsEach account is configured via numbered environment variables:
Variable | Required | Default | Description |
| Yes | Short name used in tool calls | |
| Yes | Email address | |
| Yes | IMAP server hostname | |
| No |
| IMAP port |
| Yes | SMTP server hostname | |
| No |
| SMTP port |
| No |
|
|
| Yes | Login username | |
| Yes | Login password | |
| No |
| Folder name for soft deletes |
Add as many accounts as needed by incrementing N (1, 2, 3...). Gaps in numbering are handled gracefully.
3. Run the server
python -m src.serverStarts on port 8000 with streamable-http transport by default.
4. Connect to Claude Desktop
Add as a remote MCP server in Claude Desktop settings:
https://imap-mcp.devonwatkins.com/mcpOr for local development:
{
"mcpServers": {
"imap": {
"url": "http://localhost:8000/mcp"
}
}
}Related MCP server: email-mcp
Tools
Tool | Description |
| List all configured accounts with connection status |
| List emails with filters (folder, unread, date, search) |
| Read full email content by UID (uses PEEK, does not mark as read) |
| Full-text search across folders |
| Send email via SMTP (generates Message-ID) |
| Mark emails as read/unread |
| Move emails between folders |
| List mailbox folders |
| Delete emails (soft: move to trash, or permanent) |
Every tool (except imap_list_accounts) takes an account parameter matching the account NAME.
Health Endpoints
Endpoint | Purpose |
| Combined status with per-account details |
| Liveness probe (process is up) |
| Readiness probe (at least one account can authenticate) |
The readiness endpoint actively probes IMAP connectivity — it does not rely on cached state.
{"status": "ready", "accounts": {"adjustright": "connected", "watkinshomesales": "connected"}}Error Handling
All tools return structured errors with stable codes:
{"error": true, "code": "AUTH_FAILED", "message": "...", "account": "adjustright"}Error codes: AUTH_FAILED, CONNECTION_TIMEOUT, FOLDER_NOT_FOUND, EMAIL_NOT_FOUND, SEND_FAILED, ACCOUNT_NOT_FOUND
Docker
docker build -t imap-mcp-server .
docker run -p 8000:8000 --env-file .env imap-mcp-serverThe Dockerfile includes bws CLI for fetching passwords from Bitwarden Secrets Manager at startup via start.sh.
Production Deployment
Deployed on Coolify as a Flavor A app (single container, source build).
Domain:
https://imap-mcp.devonwatkins.comPasswords: Fetched from BWS at startup (
start.sh)Health check:
/health/liveon port 8000
Tests
pip install pytest pytest-asyncio
python -m pytest tests/ -vE2E Tests
# Read-only tests against production
python scripts/test_live.py
# Include mark/move/delete tests (restores state after)
python scripts/test_live.py --destructive
# Include send test (sends email to self)
python scripts/test_live.py --send
# Full suite
python scripts/test_live.py --destructive --send
# Test a specific account
python scripts/test_live.py --account watkinshomesalesArchitecture
src/
server.py — FastMCP app, 9 tool definitions, health endpoints
client.py — Async IMAP (aioimaplib) and SMTP (aiosmtplib) clients
accounts.py — Account registry from IMAP_ACCOUNT_N_* env vars
models.py — Pydantic models for all request/response types
errors.py — Typed exceptions (AuthenticationError, FolderNotFoundError, etc.)
tests/ — 59 unit tests
scripts/ — E2E test suite and debug tools
start.sh — Entrypoint that fetches BWS secrets before starting serverKey Design Decisions
Regular SEARCH, not UID SEARCH: Namecheap Private Email doesn't support UID SEARCH. We use regular SEARCH for sequence numbers, then FETCH (UID) to convert to stable UIDs.
Per-account asyncio.Lock: Prevents concurrent requests from corrupting IMAP folder selection state.
BODY.PEEK[]: Read operations never mark emails as read.
Lazy connections: IMAP connections are established on first use, not at startup. The readiness endpoint probes real connectivity.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Connect any mailbox to Claude, ChatGPT & AI: read, send, reply, schedule & search emails.
Your mailboxes in ChatGPT and Claude: Gmail, iCloud, Fastmail, any IMAP. Passwords stay yours.
Bring Gmail, Outlook, iCloud Mail, Yahoo Mail, Fastmail and other IMAP mailboxes together. Search connected email, including semantic search; cached or indexed results may be incomplete or stale. Read messages and attachments, create drafts, send or reply when requested, and manage rules for new mail. Separate permissions control reading, attachments, drafts, sending and mailbox changes.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables Claude to interact with email accounts via IMAP and SMTP, providing tools for searching, reading, sending, and managing emails across multiple providers.40931 npm130MIT
- FlicenseNot gradedqualityBmaintenanceEnables Claude to read, search, draft, send, flag, and move email across multiple IMAP/SMTP mailboxes while keeping credentials local.-
- AlicenseNot gradedqualityBmaintenanceEnables Claude to read, search, send, and manage email across multiple IMAP/SMTP accounts through OAuth 2.1-secured MCP tools.MIT
- AlicenseAqualityBmaintenanceLets Claude Desktop read any IMAP mailbox and send emails via SMTP, with support for multiple mailboxes and locally stored credentials.1336 npmMIT