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 find the invoice from Hetzner"
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.
All your mailboxes, one MCP server, read-only.
Point it at any number of IMAP accounts (Gmail, Fastmail, iCloud, Migadu, self-hosted, anything that speaks IMAP) and your MCP client can list, search, and read across every one of them in a single call. Ask "what's unread across all my accounts?" or "find the invoice from Hetzner" and get answers that span providers, not one inbox at a time.
Strictly read-only. No send, no delete, no flag changes, no folder moves.
Every fetch uses BODY.PEEK, so reading a message never marks it as read.
Your mailboxes look exactly the same after a session as before it.
No secrets on disk. The config file names an environment variable per account; passwords only ever exist in the server process environment. Bring your own secret manager, or just export a variable.
Assistant mail integrations usually connect one Gmail or one Outlook account. IMAP is the protocol nearly every provider already speaks, so one small server covers your whole mail footprint with a single read-only code path, no OAuth apps to register, and nothing granted write access.
Related MCP server: Gmail MCP Server
Requires Python 3.12+ and uv.
git clone https://github.com/LeeFlannery/imap-mcp
cd imap-mcp
cp accounts.example.toml accounts.toml
$EDITOR accounts.toml # add your accounts
export PERSONAL_IMAP_PASSWORD='...'
uv run imap-mcp # starts the MCP server on stdioThat's it. Register it with your MCP client (below) and start asking about your mail.
accounts.toml is gitignored and holds no secrets:
[[account]]
key = "personal" # short id used in tool calls
label = "you@example.com (Fastmail)" # optional, defaults to email
email = "you@example.com" # IMAP login
host = "imap.fastmail.com"
port = 993 # optional, defaults to 993
password_env = "PERSONAL_IMAP_PASSWORD" # env var holding the password
enabled = true # optional, defaults to trueAdd one [[account]] block per mailbox. enabled = false keeps an account
listed but never logs into it. Set IMAP_MCP_ACCOUNTS=/path/to/accounts.toml
to keep the config outside the repo.
Provider | Host | Password |
Gmail / Google Workspace |
| App password (requires 2FA; the spaces Google shows are stripped automatically) |
Fastmail |
| |
iCloud |
| |
Yahoo |
| |
Migadu |
| Mailbox password |
Outlook.com / Microsoft 365 | not supported | Microsoft has retired IMAP basic auth; OAuth is not implemented here |
All standard providers use port 993 (implicit TLS), the default.
Each account's password_env names an environment variable that must be set
when the server runs. Any of these work:
# plain export in the shell that launches your MCP client
export PERSONAL_IMAP_PASSWORD='...'
# direnv, sops, pass, whatever you already use
# 1Password: put op:// references in an env file and wrap the command
op run --env-file=op.env -- uv run imap-mcpclaude mcp add imap -- uv run --directory /path/to/imap-mcp imap-mcpOr in .mcp.json / your user MCP config:
{
"mcpServers": {
"imap": {
"command": "uv",
"args": ["run", "--directory", "/path/to/imap-mcp", "imap-mcp"]
}
}
}Same command and args in the client's MCP server config
(claude_desktop_config.json, etc.). Any stdio MCP client works.
Either way, the password env vars must be visible to the spawned process:
export them in the environment the client launches from, or wrap the command
in your secret injector, e.g. "command": "op",
"args": ["run", "--env-file=/path/to/op.env", "--", "uv", "run", ...].
list_accounts() configured accounts with live status. Run this first;
it tells you which mailboxes are queryable and what to pass as account.
{"account": "personal", "email": "you@example.com", "enabled": true, "status": "ok"}list_emails(account?, since?, unread_only?, limit?) recent mail, newest
first. Omit account to merge all enabled accounts into one timeline.
search_emails(query, account?, since?, limit?) free-text search over
sender, subject, and body. Also cross-account unless you name one.
Both return compact rows:
{"account": "personal", "id": "4711", "from": "billing@hetzner.com",
"subject": "Invoice 2026-07", "date": "2026-07-03T09:12:44+00:00",
"unread": true, "snippet": "Your invoice for July..."}get_email(account, id) one full message by the id from a row, with
plain-text body preferred over HTML. Reading it does not mark it read.
Dates are ISO (YYYY-MM-DD); since filters everywhere; limit applies per
account when merging. If one account is down, its error comes back as a row
and the other accounts still answer.
status: "no-credential": the account's password_env variable is not
set in the server's environment. Remember the server inherits its env from
whatever launched it (your MCP client), not from your interactive shell.
status: "unreachable: MailboxLoginError" on Gmail/iCloud/Yahoo: you're
using the account password; these providers require an app password (see
cheat sheet).
Config not found: the server looks for accounts.toml next to
pyproject.toml, or wherever IMAP_MCP_ACCOUNTS points.
uv run pytest31 tests, no network: the IMAP layer is faked. The suite locks in the
read-only contract (mark_seen=False on every fetch), per-account error
isolation, and config handling.
MIT
Fetch one full email (plain-text body preferred) by account + message id.
id is the value returned in list_emails/search_emails rows (IMAP UID).
Reading does not mark the message as read.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| account | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a key side-effect: 'Reading does not mark the message as read' and notes 'plain-text body preferred'. This adds meaningful behavioral context beyond the schema.
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?
The description is concise, with the main purpose front-loaded in the first sentence. Each subsequent sentence adds specific value (id provenance and no-read side-effect). No filler or repetition.
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?
Given no annotations and no output schema, the description covers critical aspects: what it fetches, how to obtain the ID, and the no-mark-read behavior. It does not detail return structure but is sufficient for correct invocation.
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 adds semantic meaning to 'id' as an IMAP UID from list/search results. 'account' is mentioned but not elaborated, though this is intuitive given sibling list_accounts.
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 clearly states it 'Fetch one full email' by account and message id, using a specific verb and resource. It distinguishes from siblings by emphasizing 'full email' versus listing or searching.
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?
It explicitly explains that the id comes from list_emails/search_emails rows, implying these tools should be used first to obtain the ID. It does not explicitly contrast with alternatives but provides clear contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List configured mail accounts and whether each is reachable right now.
Performs a live IMAP login per enabled account. Returns status so the caller knows which mailboxes are queryable.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a live IMAP login per enabled account and that it returns status, which informs the agent of a network-dependent operation and the type of result. This adds meaningful behavioral context beyond the bare 'list accounts' purpose.
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?
The description is two short sentences, front-loaded with the main purpose, and every sentence adds value. It efficiently communicates scope, behavior, and outcome without unnecessary detail.
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 zero-parameter tool with an output schema, the description is quite complete. It explains the live login behavior and that the returned status tells which mailboxes are queryable. The only minor gap is lack of explicit error/failure behavior, but the output schema likely covers that.
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 the baseline is 4. The description does not need to clarify parameter semantics, and no additional parameter details are required.
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 clearly states the tool's verb and resource: 'List configured mail accounts and whether each is reachable right now.' This distinguishes it from sibling tools (list_emails, search_emails, get_email) which focus on emails, not account status.
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?
The description implies usage context: it performs a live IMAP login to check reachability, so it should be used when the caller needs to know which mailboxes are queryable. However, it does not explicitly state when to use this tool versus alternatives or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent emails, newest first.
account: account key (see list_accounts). Omit to merge ALL enabled accounts.
since: ISO date (YYYY-MM-DD) lower bound, optional.
unread_only: only unseen messages.
limit: max rows (per account when merging).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| since | No | ||
| account | No | ||
| unread_only | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals important behaviors: newest-first ordering, merging of all enabled accounts when account is omitted, per-account limit handling, unread_only filtering, and ISO date lower bound for 'since'. This goes beyond a minimal description, though it does not cover edge cases like pagination or error handling.
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?
The description is highly concise and well-structured: a one-sentence purpose followed by a parameter list. Each line is informative and necessary, with no redundant filler. The front-loaded purpose makes the tool's intent immediately clear.
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 list tool with an existing output schema, the description covers key behavioral aspects: sorting order, account scoping, and filtering semantics. It also explains the merging behavior, which is crucial for understanding results. Minor gaps include a precise definition of 'recent' and explicit handling of pagination, but the output schema and limit parameter mitigate this.
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 input schema has zero descriptions (0% coverage), so the description fully compensates by explaining every parameter: account key source and merging behavior, since as ISO date lower bound, unread_only as unseen messages, and limit as max rows per account when merging. This adds significant meaning beyond the raw schema types and defaults.
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 clearly states the tool's function: 'List recent emails, newest first.' The verb 'list' and resource 'emails' are specific, and the sorting order adds clarity. It is distinct from sibling tools like search_emails (which implies filtering/search) and get_email (which implies fetching a single email).
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?
The description provides usage context through parameter explanations, including referencing list_accounts for the account key. However, it does not explicitly state when to use this tool over search_emails or get_email, nor does it mention exclusions. The usage guidance is implied rather than explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search emails across from/subject/body text, newest first.
query: free text; matched against sender, subject, and body (IMAP OR).
account: omit to search ALL enabled accounts.
since: ISO date (YYYY-MM-DD) lower bound, optional.
limit: max rows (per account when merging).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| since | No | ||
| account | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden and does well: it discloses search fields, IMAP OR matching, account-scoping behavior, ISO date bound, and per-account limit merging. It avoids describing return values that the output schema covers, but could add slightly more about result shape.
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?
The description is concise and front-loaded with the core action in the first sentence, followed by a tight parameter-by-parameter breakdown. Every line adds necessary information without redundancy or filler.
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?
The tool has an output schema, so return-value explanation is unnecessary. The description covers the search semantics, parameter behaviors, and important edge cases like account omission and per-account limit merging, making it complete for effective invocation.
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 schema descriptions are empty (0% coverage), but the description explains every parameter meaningfully: query is free text matched against specific fields, account can be omitted for all accounts, since is an optional ISO date lower bound, and limit is max rows per account when merging. This fully compensates for the schema gaps.
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 'Search' with a clear resource 'emails' and explicitly scopes to 'from/subject/body text' with 'newest first' ordering. This distinguishes it from sibling tools like list_emails or get_email, which imply different operations.
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?
The description gives practical usage guidance: query semantics, account omission to search all accounts, optional since lower bound, and limit behavior. It does not explicitly name sibling tools as alternatives, but the context and phrasing clearly imply when to search versus list or fetch.
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.
v0.1.0get_emaillist_accountslist_emailssearch_emailsScored across 4 tools
Each tool targets a distinct operation: listing accounts, listing emails, searching emails, and fetching a single email. There is no overlapping purpose between them, and the parameters clearly differentiate list_emails from search_emails.
All tools follow a consistent verb_noun snake_case pattern: list_accounts, list_emails, search_emails, get_email. The naming is predictable and uniform.
With 4 tools, the server is well-scoped for basic email retrieval. Each tool earns its place, covering the essential actions without unnecessary bloat or redundancy.
The set covers the core email-reading workflow: identify accounts, list/search emails, and fetch full content. Minor gaps like flag management or folder operations exist, but the primary use case is fully supported.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
A MCP server for Gmail that lets you search, read, and draft emails and replies.
MCP server for MailTempo's public free temporary email inboxes.
An MCP server that provides email capabilities, hosted on Alpic platform
