MCP-postale.io

MCP server for the postale.io email hosting API.

Manage your postale.io account from any MCP-compatible AI agent — Claude Code, Claude Desktop, OpenAI Codex, Cursor, Windsurf and more. Full coverage of the official API: domains, DNS/DKIM records, white-label branding, mailboxes, Sieve filters, quotas, aliases, and email/authentication logs.

Documentación en español: README.es.md · AI agent install guide: llms-install.md · Full tool reference: docs/TOOLS.md

Features

• 31 tools covering all 39 endpoints of the postale.io API v1

• Domains — list, create (MX or TXT verification), update limits/catch-all/forwarding, delete

• DNS — suggested MX, SPF, DKIM, DMARC, verification TXT, autoconfig/autodiscover records, with the currently-found values so you can verify your DNS setup

• DKIM — inspect, generate, install (bring your own keys) and remove key pairs

• Branding — white-label webmail/admin: logos, favicon, support URL, colors, custom CSS

• Mailboxes — full CRUD, Sieve filter scripts, storage quotas, admin roles

• Aliases — full CRUD with multiple redirect targets

• Logs — daily email logs with raw SMTP/LMTP transcripts, and authentication logs for security auditing

• Safety — destructive operations (deleting domains, mailboxes, aliases, DKIM keys) require an explicit confirm: true argument, so an agent can never delete data by accident

Related MCP server: Mailcow MCP Server

Requirements

• Node.js ≥ 18

• A postale.io account on a plan with API access

• Your API key: postale.io admin panel → Account → API

Installation

Quick install (recommended)

The package is published on npm as postale-mcp — no clone or build needed:

claude mcp add postale \
  --env POSTALE_API_KEY=your_api_key_here \
  -- npx -y postale-mcp

For other clients, use npx as the command with args ["-y", "postale-mcp"] in the JSON/TOML examples below. (Running straight from GitHub also works: npx -y github:fmendezy/MCP-postale.io.)

From source

Get the code and build it:

git clone https://github.com/fmendezy/MCP-postale.io.git
cd MCP-postale.io
npm install   # also builds via the prepare script

The server binary is dist/index.js. All clients below use the same two things: the command node /absolute/path/to/MCP-postale.io/dist/index.js and the environment variable POSTALE_API_KEY.

Claude Code

claude mcp add postale \
  --env POSTALE_API_KEY=your_api_key_here \
  -- node /absolute/path/to/MCP-postale.io/dist/index.js

Then run /mcp inside Claude Code to verify the connection. Add --scope user to make it available in every project.

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "postale": {
      "command": "node",
      "args": ["/absolute/path/to/MCP-postale.io/dist/index.js"],
      "env": { "POSTALE_API_KEY": "your_api_key_here" }
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.postale]
command = "node"
args = ["/absolute/path/to/MCP-postale.io/dist/index.js"]

[mcp_servers.postale.env]
POSTALE_API_KEY = "your_api_key_here"

Cursor / Windsurf / other MCP clients

Any client that supports stdio MCP servers works with the same JSON shape as Claude Desktop above (Cursor: .cursor/mcp.json; Windsurf: ~/.codeium/windsurf/mcp_config.json).

Configuration

Available tools

See docs/TOOLS.md for every parameter and example prompts.

List endpoints are paginated (max 25 items per page) and accept an optional search query — the same rules as the underlying API.

Example prompts

Once connected, ask your agent things like:

• "List all my postale.io domains and tell me which ones have no DKIM keys."

• "Create the mailbox soporte@example.com with a strong random password."

• "Check whether the SPF and DMARC records of example.com match what postale.io suggests."

• "Show me yesterday's failed delivery attempts for example.com and the SMTP transcript of the first one."

• "Add a Sieve rule to ventas@example.com that files messages from @cliente.com into the folder Clientes." (the agent should fetch the current script first, then submit the merged script)

• "Who logged into IMAP on 2026-08-01 from an IP outside Chile?"

Security notes

• The API key grants full control over the account: treat it like a root password. Prefer per-client config files with restrictive permissions over shell profiles.

• Destructive tools require confirm: true; agents will ask you before deleting anything if you instruct them to confirm destructive actions (recommended).

• The server talks only to https://postale.io (or your POSTALE_BASE_URL) and never stores or logs your key.

Development

npm install
npm run build   # compile TypeScript to dist/
npm test        # smoke test: MCP handshake, tool list, validation, error handling
npm run dev     # tsc --watch

The project is intentionally small: src/client.ts (HTTP client with Basic auth and error mapping), src/tools.ts (tool definitions with zod schemas), src/index.ts (stdio entry point).

Issues and PRs are welcome.

License

MIT