mcp-imap mcp

v1.2.1 · MCP Tool · communication · registry.pascalai.org

Reads and manages email via IMAP4. REQUIRED params: host, username, password, operation (folders/list/get/search/move/delete/mark). Gmail: {host:'imap.gmail.com',port:993,ssl:'ssl',username:'user@gmail.com',password:'apppassword',operation:'folders'}. Always use ssl='ssl' with port 993 and app password (not account password). Returns {folders:[...]} for folders, {messages:[...]} for list/get/search.

imapemailreadmailinbox

Input Parameters

ParameterTypeDescription
hostrequired string IMAP server hostname. Gmail: imap.gmail.com. Outlook: outlook.office365.com.
portoptional integer IMAP port. Default 993 for ssl, 143 for starttls. Default: 993.
ssloptional string TLS mode: ssl=implicit TLS port 993 (default), starttls=STARTTLS port 143, none=no encryption. One of: ssl, starttls, none. Default: ssl.
usernamerequired string IMAP username (the email address).
passwordrequired string IMAP password or App Password (Gmail requires App Password).
operationoptional string folders=list mailboxes, list=message headers, get=full message by uid, search=by from_str/subject_str, move=copy+delete uid, delete=delete uid, mark=flag/unflag uid. One of: folders, list, get, search, move, delete, mark. Default: folders.
folderoptional string Folder/mailbox name. Default: INBOX. Default: INBOX.
uidoptional string Message UID string. Required for: get, move, delete, mark.
filteroptional string Filter for list operation: all (default), unseen, seen, flagged. One of: all, unseen, seen, flagged. Default: all.
from_stroptional string Search in FROM header (for list and search operations).
subject_stroptional string Search in SUBJECT header (for list and search operations).
limitoptional integer Max messages to return for list/search. Default: 20. Default: 20.
dest_folderoptional string Destination folder for move operation.
mark_asoptional string For mark operation: read, unread, flagged, or unflagged. One of: read, unread, flagged, unflagged.

Output Fields

FieldTypeDescription
folders array[string] List of mailbox names (folders operation).
messages array[object] Array of message objects with uid, from, subject, date (list/search/get).
total integer Total matching messages found.
returned integer Number of messages returned (may be less than total due to limit).
ok boolean Success flag for move/delete/mark operations.
uid string UID of the affected message (move/delete/mark).

Examples

List Gmail folders

// Input
{
  "host": "imap.gmail.com",
  "port": 993,
  "ssl": "ssl",
  "username": "user@gmail.com",
  "password": "apppassword",
  "operation": "folders"
}

// Output
{
  "folders": [
    "INBOX",
    "[Gmail]/Sent Mail",
    "[Gmail]/Trash"
  ]
}

List unread messages in INBOX

// Input
{
  "host": "imap.gmail.com",
  "port": 993,
  "ssl": "ssl",
  "username": "user@gmail.com",
  "password": "apppassword",
  "operation": "list",
  "folder": "INBOX",
  "filter": "unseen",
  "limit": 10
}

// Output
{
  "folder": "INBOX",
  "total": 3,
  "returned": 3,
  "messages": []
}

Get full message by UID

// Input
{
  "host": "imap.gmail.com",
  "port": 993,
  "ssl": "ssl",
  "username": "user@gmail.com",
  "password": "apppassword",
  "operation": "get",
  "folder": "INBOX",
  "uid": "12345"
}

// Output
{
  "uid": "12345",
  "from": "sender@example.com",
  "subject": "Hello",
  "body": "Message body text"
}

Install & Discovery

Install

ppm install mcp-imap

Get JSON Schema

GET /v1/packages/mcp-imap/1.2.1/schema

Discover by keyword

GET /v1/mcp/discover?q=imap
Discovery hint: Install with ppm install mcp-imap or invoke remotely via POST /v1/invoke/mcp-imap on the MCP Service.