Which integrations are available for this server?

Allows reading, sending, searching, and managing emails via Gmail's IMAP/SMTP interface, including multi-account support, encryption, and attachment handling.

How do I use mail-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mail-mcp list my last 5 emails from inbox" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mail-mcp

by anishhs-gh

Overview Schema Related Servers Score Discussions

TypeScript

Remote

mail-mcp

A self-hosted MCP server that gives AI agents full email superpowers.

Read, search, send, reply, manage mailboxes and accounts — over any SMTP/IMAP provider.

License: MIT Node @mailts/core

✨ Features

Feature	Description
📨 20 MCP tools	Read, search, send, reply, forward, draft, flag, move, delete, bulk send, templates, queue
🔐 Secure multi-account	Credentials encrypted at rest (AES-256-GCM); passwords never pass through the agent
⚡ Efficient reads	BODYSTRUCTURE-driven selective fetch — text only, no attachment bytes wasted
🗄️ Postgres-backed	Accounts managed at runtime via the agent; persists across restarts
🌐 Provider-agnostic	Gmail, Fastmail, Outlook, or any IMAP/SMTP server
🐳 Docker-ready	Single container; deploy to Cloud Run, Fly.io, Railway, or anywhere

Related MCP server: Agent Email

🚀 Quick Start

Single account (no database needed)

# .env
API_KEYS=your-secret-key

IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USER=you@gmail.com
IMAP_PASS=your-app-password

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=you@gmail.com
SMTP_PASS=your-app-password

npm install && npm run dev
# → Listening on http://localhost:3000/mcp

Multi-account with Postgres

# .env
API_KEYS=your-secret-key
DATABASE_URL=postgresql://user:pass@host/dbname?sslmode=require
MAIL_MCP_SECRET=any-random-string-32-chars
SERVER_URL=https://your-server.example.com

# Optional default account (always loaded from env)
IMAP_HOST=imap.gmail.com
IMAP_USER=you@gmail.com
IMAP_PASS=your-app-password
SMTP_HOST=smtp.gmail.com
SMTP_USER=you@gmail.com
SMTP_PASS=your-app-password

The mail_mcp_accounts table is created automatically on first run. Add more accounts via the agent at any time.

🔧 Configuration

Variable	Required	Default	Description
`API_KEYS`	✅	—	Comma-separated Bearer tokens for MCP auth
`DATABASE_URL`	Multi-account	—	Standard Postgres connection string
`MAIL_MCP_SECRET`	With DB	—	Encryption key for credentials at rest
`SERVER_URL`	Recommended	—	Public URL — shown in agent password setup guides
`PORT`	No	`3000`	HTTP listen port
`IMAP_HOST` / `SMTP_HOST`	No	—	Single default account from env

Copy .env.example to .env and fill in your values.

Config loading order

IMAP_HOST / SMTP_HOST  →  always loaded as the "default" account
DATABASE_URL           →  additionally loads more accounts from Postgres
Neither set            →  startup error

📧 MCP Tools

Tool	Description
`list_emails`	List emails with optional filters (unread, limit)
`get_email`	Fetch full email — text/html via BODYSTRUCTURE, attachment metadata from structure tree
`search_emails`	Search by from, to, subject, body, date range, flags
`get_thread`	Fetch full conversation thread by Message-ID
`get_attachments`	List attachment metadata or download with base64 content
`watch_inbox`	Watch for new emails via IMAP IDLE

Tool	Description
`send_email`	Send immediately via SMTP or HTTP transport
`reply_email`	Reply to a message — auto-fills In-Reply-To / References
`reply_all_email`	Reply-all, excluding self from recipients
`forward_email`	Forward with original body quoted
`save_draft`	Save to Drafts folder
`send_calendar_invite`	Send iCal VEVENT with RSVP

Tool	Description
`bulk_send`	Send personalised emails to a list with per-row variable substitution
`bulk_send_calendar_invite`	Send individual calendar invites to a list
`define_template`	Define a reusable email template with variables
`list_templates`	List defined templates
`preview_template`	Preview a template with sample data
`send_template`	Send using a defined template

Tool	Description
`queue_email`	Enqueue for async delivery with retries and priority
`queue_stats`	View queue depth and processing stats
`queue_pause` / `queue_resume`	Pause or resume the queue
`queue_drain`	Wait for queue to empty
`queue_cancel`	Cancel a queued message
`list_dead_letters`	List permanently failed messages
`retry_dead_letter`	Retry a dead-lettered message

Tool	Description
`mark_emails`	Set/clear seen, flagged, answered
`move_emails`	Move to another mailbox (IMAP MOVE or COPY+DELETE)
`copy_emails`	Copy to another mailbox
`delete_emails`	Permanently delete (mark + EXPUNGE)
`sync_incremental`	Fetch messages changed since a CONDSTORE mod-sequence

Tool	Description
`list_mailboxes`	List all IMAP folders
`get_mailbox_status`	Message counts and sync metadata
`create_mailbox`	Create a new folder
`rename_mailbox`	Rename a folder
`delete_mailbox`	Delete a folder

Tool	Description
`list_accounts`	List accounts with default status and capabilities
`add_account`	Add account to DB — returns curl command for password setup
`update_account`	Update host, port, user, label
`remove_account`	Remove account from DB
`set_default_account`	Switch the default account
`reload_config`	Reload accounts without restarting
`health_check`	Live IMAP/SMTP connectivity probe

🔑 Secure Password Flow

Passwords never pass through the agent. The agent guides you to set them directly:

You: "Add my work Gmail, imap.gmail.com, work@company.com"

Agent: Account "work" saved. Set your credentials:

  curl -X POST https://your-server/accounts/work/password \
    -H "Authorization: Bearer <your MAIL_MCP_SECRET value>" \
    -H "Content-Type: application/json" \
    -d '{"imap_pass":"your-app-password","smtp_pass":"your-app-password"}'

  Credentials are encrypted at rest. Account activates immediately.

🌐 HTTP Endpoints

Method	Path	Auth	Description
`GET`	`/health`	None	Server health check
`GET`	`/accounts`	`API_KEYS`	List accounts (no passwords)
`PATCH`	`/accounts/:name`	`API_KEYS`	Update non-sensitive fields
`DELETE`	`/accounts/:name`	`API_KEYS`	Remove an account
`POST`	`/accounts/:name/password`	`MAIL_MCP_SECRET`	Set encrypted credentials

The password endpoint deliberately uses MAIL_MCP_SECRET — not API_KEYS — so the agent (which knows API_KEYS) is cryptographically prevented from setting credentials.

🚢 Deployment

Docker

docker build -t mail-mcp .
docker run -p 3000:3000 --env-file .env mail-mcp

Cloud Run (GCP)

gcloud run deploy mail-mcp \
  --image gcr.io/YOUR_PROJECT/mail-mcp \
  --region us-central1 \
  --allow-unauthenticated \
  --update-secrets="DATABASE_URL=DATABASE_URL:latest,API_KEYS=API_KEYS:latest,MAIL_MCP_SECRET=MAIL_MCP_SECRET:latest" \
  --set-env-vars="SERVER_URL=https://your-service-url"

See deploy/ for Fly.io, Azure Container Apps, and AWS App Runner guides.

CI/CD

Two workflows:

ci.yml — runs automatically on every push to main and every PR:

Typecheck → Build → Test → Security audit (parallel)

deploy.yml — triggered manually from GitHub Actions → Run workflow:

Leave version empty → reads version from package.json, creates git tag, deploys
Enter version (e.g. v0.1.0) → rollback to that existing tag's original commit
Source code on main is never modified by deploys or rollbacks

Two separate approval gates:

Gate	Environment	Action
1	`tag`	Create / validate the release tag
2	`production`	Build image and deploy to Cloud Run

Required GitHub secrets:

GCP_PROJECT_ID · GCP_REGION · GCP_WORKLOAD_IDENTITY_PROVIDER · GCP_SERVICE_ACCOUNT · SERVER_URL

GCP Secret Manager secrets: DATABASE_URL, API_KEYS, MAIL_MCP_SECRET

Set up both environments in GitHub → Settings → Environments with required reviewers.

🛠️ Development

git clone https://github.com/anishhs-gh/mail-mcp
cd mail-mcp
npm install
cp .env.example .env   # fill in your credentials
npm run dev            # hot reload on http://localhost:3000
npm test               # 22 unit tests
npm run build          # production build

⚡ Powered by @mailts/core

mail-mcp is built on top of @mailts/core — a modern, native TypeScript SMTP/IMAP library with zero legacy dependencies, built from the ground up for Node 18+.

What mailts brings to this MCP:

BODYSTRUCTURE parsing — selective MIME section fetch means only text parts are downloaded when reading email; attachment bytes are never transferred unless explicitly requested
ImapSession.search() — full IMAP SEARCH through the session lock, no raw client exposure
textOnly fetch mode — BODYSTRUCTURE-driven, fetches text/plain and text/html only in a single round-trip
Native TLS, DKIM, OAuth2, IDLE — zero legacy dependencies, built for Node 18+
SMTP queue with priority scheduling — built-in retry logic, dead-letter handling, and external queue driver support

mailts is also open source — check it out at github.com/anishhs-gh/mailts

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md first.

📄 License

Built by Anish Shekh

GitHub LinkedIn Website

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/anishhs-gh/mail-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server