Skip to main content
Glama
imap-mcp

imap-mcp

by bahricanli

🇬🇧 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.

Mail accounts screen

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

list-accounts

The user's accounts and whether writing is allowed

list-folders

Folders with total/unread counts

search-emails

Search by from / to / subject / text / since / before / unseen; summary list without bodies (max 50)

get-email

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

get-email + move_to / mark_seen

After reading, move the message to a folder and/or mark it seen

move-emails

Move messages (max 50) to another folder

flag-emails

Mark seen/unseen, flagged/unflagged

create-folder

Create a folder (non-ASCII names supported)

delete-emails

Default: move to Trash. permanent=true: permanently delete, only from the Trash folder

delete-folder

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-mcp
curl -O https://raw.githubusercontent.com/bahricanli/imap-mcp/main/docker-compose.release.yml
curl -o .env https://raw.githubusercontent.com/bahricanli/imap-mcp/main/.env.example

Set APP_URL, APP_KEY, NPM_NETWORK and APP_PORT in .env, then:

docker compose -f docker-compose.release.yml up -d
docker compose -f docker-compose.release.yml exec mail-mcp php artisan mail:create-user

Images: 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-user or 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 / idempotent hints, so Claude can ask for confirmation.

To report a vulnerability, see SECURITY.md.

Documentation

Document

Contents

Docker installation

Pre-built image or build from source, .env, Nginx Proxy Manager, updates, backups, troubleshooting

Feature guide

Every screen of the web panel, with screenshots

Docker details

Image contents, compose files, tags, CI

Architecture

Request flow, OAuth, data model, IMAP handling

Administration

Artisan commands, users, write access, logs

Development

Local setup, tests, code style

Changelog

Release notes

Contributing

How to report bugs and send changes

Security policy

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

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLMs to read, search, and manage emails via IMAP with secure, read-only access to email accounts.
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to read, send, organize, and search emails across multiple IMAP/SMTP mailboxes.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to read, search, send, and manage emails via IMAP/SMTP with OAuth 2.1 authentication, supporting folders, drafts, replies, and forwarding.
      1
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT