mcp-imap

This MCP server provides read-only access to IMAP mailboxes for clients built on the MCP framework. It exposes tools that let clients search for emails, fetch full email content, list available folders, retrieve recent messages, and toggle read/unread status. The server is designed with security in mind: it supports credential-based authentication and avoids any email sending or deletion operations. To use it, configure the IMAP connection in a .env file, start the server, and then call the available MCP tools from your client: search_emails to filter messages by sender, subject, date range, content, or unread status; get_email to retrieve a specific message by its ID; list_folders to see all mailboxes; get_recent_emails to fetch the latest messages from a folder; and mark_as_read to update the read state of a message. Each tool accepts a structured set of arguments and returns data in a predictable format suitable for integration with Claude or other LLM-based assistants.

Prerequisites:

• Node.js (LTS version) and npm installed
• Git installed
• Access to a networked IMAP account for testing

Installation steps:

1. Clone the repository git clone <repository-url> cd mcp-imap-server

2. Install dependencies npm install

3. Build the project (TypeScript to JavaScript) npm run build

4. Configure environment variables (see configuration) Create a .env file in the project root with the required IMAP settings (host, port, user, password, TLS, etc.).

5. Run in development or production mode Development: npm run dev Production: npm run build && npm start

6. Verify the server is running and accessible by the MCP client tooling you use.

Notes and tips:

• Keep IMAP credentials secure; the server is designed to avoid logging sensitive data.
• Ensure IMAP access is enabled for the chosen provider and that app passwords are used where required (e.g., Gmail/Outlook).
• The server operates in read-only mode; attempting to modify mailbox state beyond read flags will be ignored or rejected for security.
• If you encounter connection issues, verify host/port values, TLS setting, and that the IMAP server allows the connection from your environment.
• For production deployments, consider using environment-specific .env files and proper secret management for IMAP_PASSWORD.
• The MCP tools are designed to be self-descriptive; consult tool argument schemas in the README to construct valid requests.