SecureMessage Mail MCP server
Commit Nov 7, 2026Enables AI clients to manage email accounts via IMAP and SMTP, including searching, reading, sending, and organizing messages.
Also known as securemessage/mail-mcp
- Stars
- 1
- Tools
- 24
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 7, 2026
- License
- BSD-2-Clause
What is SecureMessage Mail MCP?
SecureMessage Mail enables AI clients to manage email accounts via IMAP and SMTP, including searching, reading, sending, and organizing messages. It exposes 24 tools, such as mail_connect, mail_disconnect, mail_connection_status.
Summary generated from the project's README
About SecureMessage Mail MCP server
Managing email accounts directly from an AI client is what this PHP-based server enables. It allows developers and users to search, read, send, and organize messages using IMAP and SMTP protocols. The server supports multiple accounts that can be switched at runtime and works with providers like Gmail, Microsoft 365, and Yahoo through XOAUTH2 authentication.
Running on PHP 8.4, the server is distributed as a single PHAR file that requires no external dependencies like Node.js or Composer. It provides 22 specific tools, including mail_search with over 12 filter parameters, mail_get_thread for conversation history, and mail_create_draft for preparing messages. Users can integrate it into Claude Desktop or Windsurf by configuring the command to run the PHAR file.
This tool is unique because it uses pure PHP socket clients instead of relying on the ext-imap extension. It handles complex tasks like moving messages between folders, managing flags, and retrieving attachments. It is designed for local deployment where an AI agent can interact with various mailboxes through a unified interface.
What you can do with it
- 1Search through multiple mailboxesFind specific emails using various filters like sender, subject, or date across all folders.
- 2Organize email foldersMove messages between different folders and manage labels or flags.
Written from the project's README. Every use case is checked against a quote from it.
SecureMessage Mail MCP tools 24
Detected from the READMEmail_connectmail_disconnectmail_connection_statusmail_list_mailboxesmail_open_mailboxmail_create_mailboxmail_searchmail_get_messagemail_get_headersmail_get_messagesmail_get_threadmail_delete_message
| mail_connect | — | |
| mail_disconnect | — | |
| mail_connection_status | — | |
| mail_list_mailboxes | — | |
| mail_open_mailbox | — | |
| mail_create_mailbox | — | |
| mail_search | — | |
| mail_get_message | — | |
| mail_get_headers | — | |
| mail_get_messages | — | |
| mail_get_thread | — | |
| mail_delete_message | — |
Show all 24 toolsShow fewer tools
mail_sendmail_replymail_create_draftmail_update_draftmail_mark_readmail_mark_unreadmail_set_flagsmail_move_messagemail_get_attachmentsmail_save_attachmentmail_list_instancesmail_switch_instance
| mail_send | — | |
| mail_reply | — | |
| mail_create_draft | — | |
| mail_update_draft | — | |
| mail_mark_read | — | |
| mail_mark_unread | — | |
| mail_set_flags | — | |
| mail_move_message | — | |
| mail_get_attachments | — | |
| mail_save_attachment | — | |
| mail_list_instances | — | |
| mail_switch_instance | — |
Configuration
MAIL_MCP_CONFIG
| Name | Description | |
|---|---|---|
| MAIL_MCP_CONFIG | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesecuremessage/mail-mcp is public and reachablegithub.com/securemessage/mail-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)BSD-2-Clausespdx.org/licenses/BSD-2-Clause.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-07github.com/securemessage/mail-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model24 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSecureMessage Mail MCP Server
A PHP Model Context Protocol server for IMAP/SMTP email operations, built on the Enchilada Framework. Part of the SecureMessage project.
Uses pure PHP socket IMAP/SMTP clients — no ext-imap, no Composer, no Node.js. Zero external dependencies beyond PHP 8.4 with openssl, curl, iconv, ctype, and fileinfo.
Features
- 22 tools — search, read, send, reply, drafts, attachments, threads, move, flags
- Multi-account — manage multiple mail accounts, switchable at runtime
- Unified search — single tool with 12+ filter parameters, multi-mailbox search across all folders
- Drafts — create drafts for review before sending
- Organization — move messages between folders, manage flags/labels
- Threads — retrieve full conversation threads
- OAuth/XOAUTH2 — Gmail, Microsoft 365, Yahoo via XOAUTH2 authentication
- PHAR deployment — single-file distribution, no installation required
- Built on the EnchiladaMCP library
Requirements
- PHP 8.4+ with
openssl,curl,iconv,ctype,fileinfo, andpharextensions - An IMAP/SMTP mail account (Gmail, Outlook, Fastmail, self-hosted, etc.)
Quick Start (PHAR)
Download the latest PHAR from Releases:
curl -LO https://pacyworld.dev/securemessage/mail-mcp/releases/download/v1.1.6/mail-mcp.phar
chmod +x mail-mcp.phar
Create a config file:
mkdir -p ~/.config/mail-mcp
cat > ~/.config/mail-mcp/instances.json << 'EOF'
{
"default": "personal",
"instances": {
"personal": {
"imap_host": "imap.example.com",
"imap_port": 993,
"smtp_host": "smtp.example.com",
"smtp_port": 465,
"username": "user@example.com",
"password": "your-app-password",
"tls": true
}
}
}
EOF
Start the server:
php mail-mcp.phar
For OAuth, multi-instance, and provider-specific settings, see docs/SETUP.md.
From Source
git clone https://pacyworld.dev/securemessage/mail-mcp.git
cd mail-mcp
cp config/instances.json.sample config/instances.json
# Edit config/instances.json with your mail server details
php bin/mail-mcp
AI Assistant Configuration
Windsurf / Cascade
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mail": {
"command": "php",
"args": ["/path/to/mail-mcp.phar"]
}
}
Claude Code / Claude Desktop
{
"mcpServers": {
"mail": {
"command": "php",
"args": ["/path/to/mail-mcp.phar"]
}
}
}
To use a config file in a non-default location:
{
"mail": {
"command": "php",
"args": ["/path/to/mail-mcp.phar"],
"env": {
"MAIL_MCP_CONFIG": "/path/to/instances.json"
}
}
}
Available Tools
| Tool | Description |
|---|---|
mail_connect |
Connect to IMAP/SMTP for a mail account |
mail_disconnect |
Disconnect from mail servers |
mail_connection_status |
Show connection state for all accounts |
mail_list_mailboxes |
List available folders |
mail_open_mailbox |
Select a folder (returns message counts) |
mail_create_mailbox |
Create a new folder |
mail_search |
Search with flexible filters (from, to, cc, subject, body, date, flags, keywords) |
mail_get_message |
Fetch single message with full content |
mail_get_headers |
Fetch raw RFC 5322 headers, folding and repeats intact |
mail_get_messages |
Fetch multiple messages (headers only) |
mail_get_thread |
Retrieve full conversation thread |
mail_delete_message |
Delete a message |
mail_send |
Send a new email (with file attachments) |
mail_reply |
Reply with quoted original message |
mail_create_draft |
Save a draft for review before sending |
mail_update_draft |
Modify an existing draft (recipients, subject, body, attachments) |
mail_mark_read |
Mark message(s) as read |
mail_mark_unread |
Mark message(s) as unread |
mail_set_flags |
Add/remove IMAP flags and keywords |
mail_move_message |
Move messages between folders |
mail_get_attachments |
List attachment metadata |
mail_save_attachment |
Save attachment to file or return as base64 |
mail_list_instances |
List configured accounts |
mail_switch_instance |
Change default account |
All tools accept an optional instance parameter to target a specific mail account.
Agent Skill
For AI-assisted setup, point your AI agent to the setup skill.
Documentation
- docs/SETUP.md — Full setup guide (auth methods, providers, IDE integration, troubleshooting)
- docs/OAUTH.md — OAuth setup for Gmail, Google Workspace, Microsoft 365
- docs/TOOLS.md — Complete tool reference with all parameters
- docs/AGENT_SKILL.md — Agent skill for AI-assisted installation
License
BSD 2-Clause — see LICENSE.
SecureMessage Mail MCP questions
What tools does SecureMessage Mail MCP provide?
It exposes 24 tools, including mail_connect, mail_disconnect, mail_connection_status, mail_list_mailboxes, mail_open_mailbox.
What authentication methods are supported?
The server supports standard password authentication and OAuth/XOAUTH2 for providers like Gmail, Microsoft 365, and Yahoo.
Does this require any external dependencies like Node.js or Composer?
No, it uses pure PHP socket clients and requires no external dependencies beyond PHP 8.4 and specific standard extensions.
Can I manage multiple email accounts at once?
Yes, the server supports multi-account management and allows you to switch between accounts at runtime.