Allows interaction with any IMAP-compatible email server such as Gmail, providing tools to list mailboxes, list, read, search, move, flag, and create draft emails.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@imap-mcp list the latest emails from my 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.
š§ An IMAP Model Context Protocol (MCP) server to expose IMAP operations as tools for AI assistants.
This MCP-Server was originally created by dominik1001 and has been forked for customization and additional features.
Related MCP server: Email MCP Server
List Mailboxes: Browse all available mailboxes with their special use flags
List Emails: View the most recent emails in any mailbox
Read Emails: Read full email content including headers and body
Search Emails: Search emails by sender, recipient, subject, date range, and flags
Move Emails: Move emails between mailboxes
Flag Emails: Add or remove flags (Seen, Flagged, Answered, etc.)
Create Drafts: Create draft emails saved to your IMAP server's drafts folder
IMAP Integration: Connect to any IMAP-compatible email server (Gmail, Outlook, etc.)
Secure Authentication: Uses environment variables for secure credential management
MCP Compatible: Works with Claude and other AI assistants that support the Model Context Protocol
MCPB Compatible: Easy integration with MCPB-compatible AI assistants like Claude Desktop
{
"mcpServers": {
...,
"imap": {
"command": "npx",
"args": [
"imap-mcp"
],
"env": {
"IMAP_HOST": "<IMAP host>",
"IMAP_PORT": "<IMAP port>",
"IMAP_USERNAME": "<IMAP username>",
"IMAP_PASSWORD": "<IMAP password>",
"IMAP_USE_SSL": "<true or false>"
}
}
}
}Compile TypeScript to JavaScript:
npx tscRun the MCP server:
node dist/index.jslist-mailboxesLists all available mailboxes on the IMAP server with their path, special use designation, flags, and subscription status.
Parameters: None
list-emailsLists the most recent emails from a mailbox.
Parameters:
mailbox (string, optional): Mailbox to list (default: "INBOX")
limit (number, optional): Number of emails to return, 1ā100 (default: 20)
read-emailReads a single email by UID, returning full headers and body content.
Parameters:
mailbox (string, optional): Mailbox containing the email (default: "INBOX")
uid (number, required): The UID of the email to read
search-emailsSearches for emails using optional filter criteria.
Parameters:
mailbox (string, optional): Mailbox to search (default: "INBOX")
from (string, optional): Filter by sender
to (string, optional): Filter by recipient
subject (string, optional): Filter by subject
since (string, optional): Emails since this ISO date
before (string, optional): Emails before this ISO date
seen (boolean, optional): Filter by read/unread status
flagged (boolean, optional): Filter by flagged status
limit (number, optional): Maximum results, 1ā100 (default: 20)
move-emailMoves an email to a different mailbox.
Parameters:
mailbox (string, optional): Source mailbox (default: "INBOX")
uid (number, required): The UID of the email to move
destination (string, required): Target mailbox path
flag-emailAdds or removes flags on an email.
Parameters:
mailbox (string, optional): Mailbox containing the email (default: "INBOX")
uid (number, required): The UID of the email
action (string, required): "add" or "remove"
flags (string[], required): Flags to modify (e.g., \Seen, \Flagged, \Answered, \Draft, \Deleted)
create-draftCreates a draft email message and saves it to the IMAP server's drafts folder.
Parameters:
to (string, required): The recipient's email address
subject (string, required): The email subject line
body (string, required): The email body content
from (string, optional): The sender's email address (defaults to IMAP_USERNAME)
MIT
Creates a draft email message
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | ||
| body | Yes | ||
| from | No | ||
| subject | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure and does very little with it. It does not say where the draft is stored, whether it is visible to recipients, whether 'from' defaults to the authenticated account, whether the draft can later be sent, or what is returned on success; for a write tool with zero annotation coverage this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler, which is efficient. It is under-specified rather than bloated, so brevity here is a mild positive rather than a structural flaw.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and 0% parameter documentation, the description is the only guidance available and it covers roughly nothing beyond the tool's existence. An agent cannot determine required inputs, the role of the optional 'from' field, or the outcome of a successful call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for all four parameters, so the description must compensate and does not. It never mentions 'to', 'subject', 'body', or the optional 'from', leaving the agent to infer the required fields and the meaning of the optional sender override from the property names only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (creates) and resource (draft email message), so an agent knows exactly what the tool produces. It does not differentiate from siblings, but none of the siblings (flag/list/move/read/search) overlap with draft creation, so the distinction is implicit rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus other tools, no prerequisites, and no mention of how a created draft relates to later sending or to read/list-email tools. The agent must infer the entire usage context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Adds or removes flags on an email message by UID
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| flags | Yes | ||
| action | Yes | ||
| mailbox | No | INBOX |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It says the tool mutates flags but discloses nothing about whether removals of absent flags error, whether flags are IMAP keywords (\Seen, \Flagged), required permissions, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One tight sentence with the verb front-loaded and no filler. It is efficient, though its brevity reflects under-specification rather than disciplined economy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A mutation tool with no annotations, no output schema, and zero parameter documentation needs substantially more than one clause. Valid flag values, error behavior, and the mailbox default are all missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It names UID and the add/remove action, but says nothing about valid flag string values (the least obvious parameter), nor that mailbox defaults to INBOX.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb pair (adds/removes) and resource (flags on an email message), plus the lookup key (UID). It reads clearly against siblings like move-email and read-email, though what a "flag" actually is remains undefined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to prefer this over siblings, no prerequisites, no note that mailbox defaults to INBOX or that flag operations are per-message. The agent must infer all usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the most recent emails from an IMAP mailbox
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| mailbox | No | INBOX |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and discloses almost nothing: no mention of auth requirements, pagination/ordering semantics, whether it marks messages as read, or rate limits. 'Most recent' hints at ordering but is not explicit about sort direction or fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence that is front-loaded with the verb and resource and contains no filler. It is efficient, though brevity here comes at the cost of the missing detail noted elsewhere.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and two completely undocumented parameters, the description is too thin. An agent lacks the information needed to know how results are ordered, how many are returned, or what side effects listing may have on message state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds essentially no parameter meaning. 'IMAP mailbox' weakly implies the mailbox parameter, but the limit parameter (default 20, max 100) and its effect on the result set are never mentioned, so the description fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Lists) and resource (emails) with a scope qualifier ('most recent') and the source system (IMAP mailbox). It does not differentiate itself from siblings like search-emails or read-email, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus search-emails (filtered retrieval) or read-email (single message body). The implied usage is only that it returns recent messages, with no exclusions or conditions stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all available IMAP mailboxes
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries full behavioral disclosure burden. It states 'all available' but omits whether the operation is read-only, whether it requires authentication, and what details each mailbox entry includes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no wasted words. Perfectly sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description does not explain the shape of returned mailbox data (e.g., names, flags, hierarchy). For a simple list tool it covers the basic purpose but leaves return-value expectations unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter semantics to document. Per rubric, 0 params baseline is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Lists') and resource ('IMAP mailboxes') with scope ('all available'). It implicitly distinguishes from sibling email-centric tools like list-emails and search-emails, so an agent can identify it unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No indication of when to use this tool versus alternatives, nor any prerequisites or context. The agent must infer that this is for enumerating mailbox folders, but no explicit guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Moves an email message to a different mailbox folder
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| mailbox | No | INBOX | |
| destination | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden but only states the action. It omits side effects (removal from source folder), permission requirements, destination-existence assumptions, and error behavior for invalid UIDs or folders.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no wasted words. The action and scope are conveyed immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter mutation tool with no annotations, no output schema, and 0% schema description coverage, the description is too thin. It conveys purpose but leaves the agent without enough operational detail to invoke the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not name or explain any parameter. It loosely implies a message identifier and destination folder, but leaves uid, the default INBOX mailbox, and the destination string constraint unclarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Moves'), resource ('email message'), and target ('a different mailbox folder'). This is unambiguous and clearly distinct from read, flag, list, search, and create-draft siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no when-to-use guidance, prerequisites, or alternatives. It does not explain when to move vs. flag or copy, nor does it mention constraints such as requiring the destination folder to already exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads a single email message by UID from an IMAP mailbox
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| mailbox | No | INBOX |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. For an IMAP read it omits the most consequential trait: whether fetching a message sets the \Seen flag, plus any auth or failure behavior. 'Reads' implies non-destructive intent but that is inference, not disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the resource and key appear immediately. It is terse to the point of under-specification, but every word earns its place structurally.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and 0% parameter coverage, the description is the only source of behavioral detail and it delivers one sentence. An agent cannot tell whether reading mutates mailbox state or what the returned message contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, yet it only echoes the field names (UID, mailbox) without adding meaning. It does not explain the mailbox default of INBOX, UID validity, or what an invalid UID yields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Reads a single email message') plus the retrieval key (UID) and source (IMAP mailbox). The word 'single' implicitly separates it from list-emails and search-emails, though it never names a sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: you call this when you already have a UID. There is no guidance on how to obtain a UID (e.g., via search-emails or list-emails), no conditions, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches for emails in a mailbox using optional filter criteria
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| from | No | ||
| seen | No | ||
| limit | No | ||
| since | No | ||
| before | No | ||
| flagged | No | ||
| mailbox | No | INBOX | |
| subject | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It says nothing about pagination (limit default 20, max 100), whether results are sorted, whether an empty result is returned vs an error, or what format the results take. For a read/search tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, tight sentence with no wasted words. Brevity alone doesn't make it complete, but structurally it is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
9 parameters, 0% schema coverage, no annotations, no output schema. The description should compensate but does not: it never enumerates the filter fields, never explains the default INBOX mailbox or the 1-100 limit range, and never describes the return shape. Inadequate for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and there are 9 parameters. The description only gestures at 'optional filter criteria' without naming a single filter (to, from, subject, since, before, seen, flagged) or explaining the mailbox default of INBOX or the limit semantics. The schema itself has no descriptions, so neither source documents the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Searches) and resource (emails) with scope 'in a mailbox'. However, it doesn't distinguish from the sibling list-emails, which also likely retrieves emails; the difference between 'search' and 'list' is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this vs list-emails or read-email. The word 'optional filter criteria' implies filters, but it never says when searching is preferable to listing, nor any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.1.0create-draftflag-emaillist-emailslist-mailboxesmove-emailread-emailsearch-emailsScored across 7 tools
Most tools have clearly distinct actions and resources (create, flag, move, read, list mailboxes), but list-emails and search-emails both retrieve email lists and could overlap when no filters are used.
All tools follow a consistent kebab-case verb-noun pattern (e.g., create-draft, list-emails, move-email), making the naming predictable and readable.
Seven tools provide a well-scoped set for core IMAP operations without redundancy; each tool earns its place for basic mailbox interaction.
Core read/search/list/move/flag/draft operations are covered, but deletion and mailbox management (create/delete/rename mailboxes) are missing, creating notable gaps for common email workflows.
Email infrastructure for AI agents ā send, receive, search, and reply to email over MCP.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Your agent needs a mailbox of its own ā to receive, thread, draft and send, with attachments, without borrowing your personal inbox or your company's SMTP. **What you can ask for** ā¢ "Create an inbox for this agent and tell me its address." ā¢ "Read the new messages in this thread and draft a reply." ā¢ "Send this message with the attachment and wait for the response." ā¢ "Search this inbox for everything from that domain." ā¢ "Show delivery metrics and the events on this inbox." **How to use it** Point any MCP client at https://mcp.aisa.one/mail/mcp and sign in with OAuth ā there is no key to create or paste. 49 tools: create and delete inboxes, list and read messages, raw message bodies, attachments, threads, drafts and draft attachments, send and reply, message search, inbox events, metrics, and list entries ā reads and writes. **Why this rather than the source** A real inbox an agent owns, rather than an SMTP credential it borrows from a human. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Find the contact elsewhere in the catalogue, then write to them from here ā without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/sales/mcp finds the person to write to.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
