imap-mcp
Connects to Gmail mailboxes over IMAP to list folders, search and read emails, and, when write access is enabled, move, flag, and delete messages.
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.
🇬🇧 English | 🇹🇷 Türkçe
imap-mcp
An MCP server that exposes IMAP mailboxes to AI clients (Claude, ChatGPT, Cursor…), protected with OAuth 2.1. Built with Laravel 13, laravel/mcp and webklex/php-imap.

More: Feature guide
Read-only by default. Creating folders, moving, flagging and deleting are enabled per account.
Read tools never mark messages as seen. It does not send mail.
A user can have several IMAP accounts; passwords are stored encrypted with
APP_KEY.Add it straight to claude.ai as a custom connector: OAuth discovery and Dynamic Client Registration are built in.
Tools
Read (every account):
Tool | What it does |
| The user's accounts and whether writing is allowed |
| Folders with total/unread counts |
| Search by from / to / subject / text / since / before / unseen; summary list without bodies (max 50) |
| One message by UID: headers, plain-text body (cut at 20k characters), attachment list |
Without criteria, search-emails looks at the last 7 days; it never scans huge mailboxes in full.
Write (only on accounts with write access; users without it never see these tools):
Tool | What it does |
| After reading, move the message to a folder and/or mark it seen |
| Move messages (max 50) to another folder |
| Mark seen/unseen, flagged/unflagged |
| Create a folder (non-ASCII names supported) |
| Default: move to Trash. |
| Delete only empty folders that have no subfolders and are not system folders |
Example prompt: "Read the unread invoices, summarise them and move all of them to Invoices/2026."
Claude finds the messages with search-emails, then calls
get-email(uid, move_to: "Invoices/2026", mark_seen: true) for each one.
Related MCP server: MCP Email
Quick start (Docker)
mkdir imap-mcp && cd imap-mcpcurl -O https://raw.githubusercontent.com/bahricanli/imap-mcp/main/docker-compose.release.ymlcurl -o .env https://raw.githubusercontent.com/bahricanli/imap-mcp/main/.env.exampleSet APP_URL, APP_KEY, NPM_NETWORK and APP_PORT in .env, then:
docker compose -f docker-compose.release.yml up -ddocker compose -f docker-compose.release.yml exec mail-mcp php artisan mail:create-userImages: ghcr.io/bahricanli/imap-mcp and bahricanli/imap-mcp (amd64 + arm64).
Full walkthrough: Docker installation.
Connecting
claude.ai: Settings → Connectors → Add custom connector →
https://your-domain/(the root URL). A login screen opens in the browser, followed by a consent screen.Claude Code:
claude mcp add --transport http mail https://your-domain/Test:
php artisan mcp:inspector /
The web panel is at https://your-domain/panel; the MCP server itself is at the root URL.
Security
Use an app password instead of your main password for Mailcow / Gmail / Outlook.
No open sign-up; users are added with
mail:create-useror by an admin in the panel. Login attempts are limited to 5 per minute.Prompt injection: email content is untrusted data. An incoming message can say "delete this folder". That is why write access is off by default and the server instructions tell the model to write only on the user's explicit request. The real safeguards are server-side:
Deleting moves to Trash first; permanent deletion only works inside Trash, as a separate step.
System folders and non-empty folders cannot be deleted.
At most 50 messages per call.
Every write is logged with user, account, folder and UIDs (
docker compose logs mail-mcp).
Write tools carry the MCP
destructive/idempotenthints, so Claude can ask for confirmation.
To report a vulnerability, see SECURITY.md.
Documentation
Document | Contents |
Pre-built image or build from source, | |
Every screen of the web panel, with screenshots | |
Image contents, compose files, tags, CI | |
Request flow, OAuth, data model, IMAP handling | |
Artisan commands, users, write access, logs | |
Local setup, tests, code style | |
Release notes | |
How to report bugs and send changes | |
Supported versions, private reporting |
Roadmap
Add / delete accounts and set write access from the web panel
Attachment download (signed, expiring URL)
Draft creation (without sending)
End-to-end IMAP tests against a real Dovecot container (CI)
License
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
Give AI agents their own email inboxes: list, read and send mail via scoped, revocable OAuth grants.
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.
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.
Email inboxes and calendars for AI agents: send, receive, search, draft and schedule.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to read, search, and manage emails via IMAP with secure, read-only access to email accounts.6MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to read, send, organize, and search emails across multiple IMAP/SMTP mailboxes.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to read, search, send, and manage emails via IMAP/SMTP with OAuth 2.1 authentication, supporting folders, drafts, replies, and forwarding.1MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to securely manage multiple email accounts via IMAP and SMTP, including searching, reading, sending, replying, forwarding, organizing folders, marking, and bulk deleting messages.931 npmMIT