Skip to content
MCP server

IMAP mailbox

IMAP mailbox server that reads, searches and files mail but cannot send any

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
0.7.0
Listing updated
2 days ago

About IMAP mailbox

IMAP mailbox is an open-source MCP server for communication. It runs locally on your machine and is started by your AI client.

The design premise is that an agent with private data, untrusted input and a way to reach the outside is exploitable by anyone who can put a message in the inbox. This server deliberately has the first two and not the third: save_draft writes a reply into your Drafts folder, and you send it from your own mail client.

Every message body arrives fenced between untrusted-content markers carrying a random nonce that is repeated on each line inside. Zero-width and directional-override characters are stripped, and markdown images are defused so a client cannot fetch a tracking pixel. Results also include SPF, DKIM and DMARC verdicts, flagged as forgeable unless you set IMAP_TRUSTED_AUTHSERV_ID, plus matches for prompt-injection patterns and mixed-script words. list_new_messages tracks what the assistant has seen with its own IMAP keyword, so reading here does not mark mail read in your client.

With only host, user and password set, it registers six read tools. Setting IMAP_READ_ONLY=false adds the writes, up to eleven tools in all, and deletes, moves, copies and folder deletion ask a person first through MCP elicitation. IMAP_ALLOW_TOOLS and IMAP_DENY_TOOLS trim the set further. It is published on npm and as a container image.

Install

Run in a terminal

claude mcp add imap-mcp --env IMAP_HOST='<IMAP_HOST>' --env IMAP_USER='<IMAP_USER>' --env IMAP_PASSWORD='<IMAP_PASSWORD>' -- npx -y @ni-c/imap-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "imap-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ni-c/imap-mcp"
      ],
      "env": {
        "IMAP_HOST": "<IMAP_HOST>",
        "IMAP_USER": "<IMAP_USER>",
        "IMAP_PASSWORD": "<IMAP_PASSWORD>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "imap-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ni-c/imap-mcp"
      ],
      "env": {
        "IMAP_HOST": "<IMAP_HOST>",
        "IMAP_USER": "<IMAP_USER>",
        "IMAP_PASSWORD": "<IMAP_PASSWORD>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "imap-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ni-c/imap-mcp"
      ],
      "env": {
        "IMAP_HOST": "<IMAP_HOST>",
        "IMAP_USER": "<IMAP_USER>",
        "IMAP_PASSWORD": "<IMAP_PASSWORD>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "imap-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ni-c/imap-mcp"
      ],
      "env": {
        "IMAP_HOST": "<IMAP_HOST>",
        "IMAP_USER": "<IMAP_USER>",
        "IMAP_PASSWORD": "<IMAP_PASSWORD>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "imap-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ni-c/imap-mcp"
      ],
      "env": {
        "IMAP_HOST": "<IMAP_HOST>",
        "IMAP_USER": "<IMAP_USER>",
        "IMAP_PASSWORD": "<IMAP_PASSWORD>"
      }
    }
  }
}

Configuration

  • IMAP_HOSTHostname of the IMAP server, e.g. imap.example.netRequired
  • IMAP_USERMailbox user nameRequired
  • IMAP_PASSWORDMailbox password or app passwordRequired
  • IMAP_PORTDefaults to 993 with implicit TLS, 143 otherwise
  • IMAP_TLSimplicit (default), starttls or none
  • IMAP_MAILBOXDefault mailbox to work in (default: INBOX)
  • IMAP_SEEN_KEYWORDIMAP keyword marking what the assistant has already seen (default: AiSeen)
  • IMAP_READ_ONLYSet to false to register the mailbox write tools; defaults to true
  • IMAP_ALLOW_TOOLSComma-separated tool names or list_* prefixes to register; 'essential' selects a curated preset (default: all tools)
  • IMAP_DENY_TOOLSComma-separated tool names or list_* prefixes to remove from whatever IMAP_ALLOW_TOOLS left
  • IMAP_DOWNLOAD_DIRDirectory attachments may be written to; unset means the server never touches the filesystem
  • IMAP_INSECURE_TLSSet to true to accept self-signed certificates, scoped to this connection
  • IMAP_DRAFTS_MAILBOXDrafts folder to save into; by default the one flagged \Drafts is used
  • IMAP_MAX_MESSAGESDefault number of messages a listing returns (default: 100)
  • IMAP_MAX_ATTACHMENT_BYTESCeiling for returning an attachment inline (default: 1048576)
  • IMAP_MAX_DOWNLOAD_BYTESCeiling for writing an attachment to disk (default: 26214400)
  • IMAP_MAX_EXTRACT_BYTESCeiling for reading a document's text with mode=text (default: 10485760, maximum: 67108864)
  • IMAP_COMMAND_TIMEOUT_SECONDSSeconds one IMAP command may take before the call is abandoned (default: 30, maximum: 600)
  • IMAP_ATTACHMENT_TYPESComma-separated content-type allowlist for attachments
  • IMAP_TRUSTED_AUTHSERV_IDauthserv-id your provider stamps into Authentication-Results; without it every verdict is reported as forgeable
  • IMAP_HOSTHostname of the IMAP server, e.g. imap.example.netRequired
  • IMAP_USERMailbox user nameRequired
  • IMAP_PASSWORDMailbox password or app passwordRequired
  • IMAP_PORTDefaults to 993 with implicit TLS, 143 otherwise
  • IMAP_TLSimplicit (default), starttls or none
  • IMAP_MAILBOXDefault mailbox to work in (default: INBOX)
  • IMAP_SEEN_KEYWORDIMAP keyword marking what the assistant has already seen (default: AiSeen)
  • IMAP_READ_ONLYSet to false to register the mailbox write tools; defaults to true
  • IMAP_ALLOW_TOOLSComma-separated tool names or list_* prefixes to register; 'essential' selects a curated preset (default: all tools)
  • IMAP_DENY_TOOLSComma-separated tool names or list_* prefixes to remove from whatever IMAP_ALLOW_TOOLS left
  • IMAP_DOWNLOAD_DIRDirectory attachments may be written to; unset means the server never touches the filesystem
  • IMAP_INSECURE_TLSSet to true to accept self-signed certificates, scoped to this connection
  • IMAP_DRAFTS_MAILBOXDrafts folder to save into; by default the one flagged \Drafts is used
  • IMAP_MAX_MESSAGESDefault number of messages a listing returns (default: 100)
  • IMAP_MAX_ATTACHMENT_BYTESCeiling for returning an attachment inline (default: 1048576)
  • IMAP_MAX_DOWNLOAD_BYTESCeiling for writing an attachment to disk (default: 26214400)
  • IMAP_MAX_EXTRACT_BYTESCeiling for reading a document's text with mode=text (default: 10485760, maximum: 67108864)
  • IMAP_COMMAND_TIMEOUT_SECONDSSeconds one IMAP command may take before the call is abandoned (default: 30, maximum: 600)
  • IMAP_ATTACHMENT_TYPESComma-separated content-type allowlist for attachments
  • IMAP_TRUSTED_AUTHSERV_IDauthserv-id your provider stamps into Authentication-Results; without it every verdict is reported as forgeable

Tools this server provides (3)

Taken from the project documentation; the running server may differ.

list_new_messages
List messages the assistant has not yet seen
save_draft
Write a reply into the Drafts folder
list_mailboxes
List mailbox folders by path and display name

What it does

Fenced untrusted content
Wraps every message body in nonce-marked boundaries.
No send capability
Saves drafts only; you send from your own client.
Read-only by default
Registers only read tools until writes are enabled.
Human approval for destructive actions
Deletes, moves, copies and folder removal prompt a person.
New-mail tracking
Uses a dedicated IMAP keyword to know what the assistant has seen.
Authentication verdicts
Reports SPF, DKIM and DMARC results with a forgeable flag.
Tool allow and deny lists
Filtered tools are not registered at all.

Good for

  • Ask an assistant what new mail arrived
  • Search a mailbox for an invoice or thread
  • Draft a reply into the Drafts folder for review
  • Sort mail into folders with approval for risky steps
  • Save an attachment to a chosen directory

Pricing

Open source

Prices change. Check imap-mcp.ni-c.de before you buy.

IMAP mailbox FAQ

Can it send email?

No. It can save a draft, and you send it yourself.

Which mail providers work?

Any IMAP mailbox, since it speaks IMAP rather than a vendor API.

What credentials are required?

IMAP_HOST, IMAP_USER and IMAP_PASSWORD, which can be an app password.

Are write tools on by default?

No. IMAP_READ_ONLY defaults to true and must be set to false.

How can a web client use it?

Through mcp-hub, which serves stdio servers over Streamable HTTP with OAuth 2.1.

Is IMAP mailbox free?

Yes. IMAP mailbox is open source, so you can use and self-host it for free.

How do I add IMAP mailbox to Claude Code?

Run this command in your terminal: claude mcp add imap-mcp --env IMAP_HOST='<IMAP_HOST>' --env IMAP_USER='<IMAP_USER>' --env IMAP_PASSWORD='<IMAP_PASSWORD>' -- npx -y @ni-c/imap-mcp

What are the best alternatives to IMAP mailbox?

The closest alternatives to IMAP mailbox are Ha MCP, Concord MCP, note1, BoardAgent and Callout.

Alternatives to IMAP mailbox

  1. Ha MCP

    MCP server

    MCP server for managing and automating Home Assistant from AI assistants

    Runs locally
    • 8 tools
    • Open source
    • 7.9K GitHub stars
    • Productivity
  2. Concord MCP

    MCP server

    Local-first MCP server for messaging and shared work-state between coding agents

    Runs locally
    • Freemium
    • 1.3K GitHub stars
    • Developer tools
  3. note1

    MCP server

    MCP server giving AI assistants search and summaries across your note1 meetings

    • 4 tools
    • Remote
    • Free trial
    • 1 GitHub star
    • Productivity
  4. BoardAgent

    MCP server

    Remote MCP server for a message board where only AI agents post, reply and vote

    • 27 tools
    • Remote
    • Free
    • Community directories
  5. Callout

    MCP server

    Let an AI agent place real phone calls in Japanese or English and read the transcript

    • 5 tools
    • Remote
    • Freemium
    • Communication
  6. CalderFlow

    MCP server

    Turn notes or specs into editable flowcharts, timelines and funnels from an AI assistant

    • 10 tools
    • Remote
    • Free
    • Design and media