zimbra-mcp

MCP server for IMAP (read) and SMTP (send), aimed at Zimbra and any standard mail host. stdio transport — works with Claude Desktop, Cursor, and other MCP clients.

npm: npmjs.com/package/zimbra-mcp · Source: github.com/TechGuyVN/zimbra-mcp

---

Requirements

• Node.js ≥ 18
• Mail with IMAP and SMTP enabled

---

Install (npm only)

npm install -g zimbra-mcp

This installs the zimbra-mcp command and the package under your global node_modules.

Entrypoint for MCP config

Use one of these in Claude/Cursor:

A — Global command (simplest if npm bin -g is on your PATH when the app starts):

{
  "command": "zimbra-mcp",
  "args": []
}

B — node + absolute path to dist/index.js (most reliable):

1. Print the global package root:

   npm root -g
   

2. Your file is:
   {that_output}/zimbra-mcp/dist/index.js
   Example macOS/Linux: /usr/local/lib/node_modules/zimbra-mcp/dist/index.js
   Example Windows (typical): C:\Users\You\AppData\Roaming\npm\node_modules\zimbra-mcp\dist\index.js

{
  "command": "node",
  "args": ["/absolute/path/to/node_modules/zimbra-mcp/dist/index.js"]
}

Always use a real absolute path in args.

Claude Desktop + nvm: Claude prepends old Node versions to PATH (e.g. v13 first). Then /usr/bin/env node inside any shebang can pick Node 13, which breaks this package (Node ≥ 18 required). Fix: set command to an absolute Node 18+ binary and args to the script:

{
  "mcpServers": {
    "zimbra-mail": {
      "command": "/Users/YOU/.nvm/versions/node/v20.19.5/bin/node",
      "args": ["/usr/local/lib/node_modules/zimbra-mcp/dist/index.js"],
      "env": {}
    }
  }
}

Adjust paths with which node (after nvm use 20) and npm root -g. You can use .../zimbra-mcp/bin/zimbra-mcp.mjs instead of dist/index.js if you prefer the npm bin entry (same Node binary in command).

---

Environment variables

Set these in the MCP env object (all values as strings). The server does not read .env by itself.

Single mailbox (flat env)

Do not set ZIMBRA_MAILBOXES_PATH. One profile named default is used; omit profile on tools.

Variable	Required	Notes
ZIMBRA_IMAP_HOST	Yes	IMAP host
ZIMBRA_IMAP_PORT	No	Default 993
ZIMBRA_IMAP_USER	Yes	Usually full email
ZIMBRA_IMAP_PASS	Yes	Password or app password
ZIMBRA_IMAP_SECURE	No	If unset: true if port 993, else false
ZIMBRA_SMTP_HOST	Yes	SMTP host
ZIMBRA_SMTP_PORT	No	Default 587
ZIMBRA_SMTP_USER	Yes	Often same as IMAP
ZIMBRA_SMTP_PASS	Yes	Often same as IMAP
ZIMBRA_SMTP_SECURE	No	If unset: true if port 465, else false
ZIMBRA_LIST_MAX	No	Max messages per list call; default 200, hard cap 1000

Ports: IMAP 993 (TLS), SMTP 587 (STARTTLS, often ZIMBRA_SMTP_SECURE=false) or 465 (SSL).

Multiple mailboxes (one JSON file)

1. Create a JSON file (see example below). chmod 600 it.
2. Set ZIMBRA_MAILBOXES_PATH to its absolute path.
3. Use tool zimbra_list_profiles, then pass profile on other tools.

Variable	Required	Notes
ZIMBRA_MAILBOXES_PATH	Yes	Absolute path to the JSON file
ZIMBRA_LIST_MAX	No	Overrides list cap (max 1000)

Minimal multi-profile JSON:

{
  "defaultProfile": "work",
  "maxListMessages": 200,
  "profiles": [
    {
      "id": "work",
      "imap": {
        "host": "mail.company.com",
        "port": 993,
        "user": "you@company.com",
        "pass": "secret"
      },
      "smtp": {
        "host": "mail.company.com",
        "port": 587,
        "user": "you@company.com",
        "pass": "secret"
      }
    },
    {
      "id": "personal",
      "imap": {
        "host": "imap.gmail.com",
        "user": "you@gmail.com",
        "pass": "app-password"
      },
      "smtp": {
        "host": "smtp.gmail.com",
        "user": "you@gmail.com",
        "pass": "app-password"
      }
    }
  ]
}

port / secure under imap/smtp are optional (defaults: IMAP 993, SMTP 587, with TLS rules same as flat env). More examples: mailboxes.example.json on GitHub.

---

Claude Desktop

Config file

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Single mailbox

{
  "mcpServers": {
    "zimbra-mail": {
      "command": "zimbra-mcp",
      "args": [],
      "env": {
        "ZIMBRA_IMAP_HOST": "mail.example.com",
        "ZIMBRA_IMAP_PORT": "993",
        "ZIMBRA_IMAP_USER": "you@example.com",
        "ZIMBRA_IMAP_PASS": "your-secret",
        "ZIMBRA_SMTP_HOST": "mail.example.com",
        "ZIMBRA_SMTP_PORT": "587",
        "ZIMBRA_SMTP_USER": "you@example.com",
        "ZIMBRA_SMTP_PASS": "your-secret"
      }
    }
  }
}

Multiple mailboxes

{
  "mcpServers": {
    "zimbra-mail": {
      "command": "zimbra-mcp",
      "args": [],
      "env": {
        "ZIMBRA_MAILBOXES_PATH": "/Users/you/.config/zimbra-mcp/mailboxes.json"
      }
    }
  }
}

Restart Claude fully after edits.

---

Cursor

Settings → MCP (or mcp.json per Cursor docs). Use the same command / args / env shape as above, then reload MCP.

---

Tools

Tool	Purpose
zimbra_list_profiles	List mailbox profiles (ZIMBRA_MAILBOXES_PATH mode).
zimbra_list_folders	List IMAP folders. Optional profile.
zimbra_list_messages	Last N messages in folder. Optional profile, limit (cap 1000).
zimbra_get_message	Read by UID. Optional profile.
zimbra_send_email	Send mail. Optional profile.

UID is scoped to folder and profile.

---

Tips

• One account, many folders: zimbra_list_folders then zimbra_list_messages per folder.
• Raise ZIMBRA_LIST_MAX if you need longer lists (≤ 1000).
• Listing is “last N by sequence”; filter by date in the model if you need “today’s mail”.

---

Troubleshooting

Issue	Check
MCP won’t start	node -v ≥ 18; if using zimbra-mcp, ensure global npm bin is on PATH.
Safer start	Use node + absolute .../zimbra-mcp/dist/index.js from npm root -g.
Auth errors	Host/port/TLS; app passwords; IMAP/SMTP enabled on server.

---

Security

• Never paste secrets into public chats; lock down JSON and Claude config files (chmod 600 where applicable).
• This MCP can read and send mail for every configured account.

---

Protocol & license

MCP · ISC — see package.json.