purelymail

PurelyMail MCP Server exposes a collection of tools that wrap PurelyMail's email management API, giving AI assistants a structured and type-safe way to manage users, domains, routing rules, billing, and password reset methods. The server is designed to be run on demand with npx, eliminating the need for a local installation, or can be run via Nix for reproducible development. Clients communicate with the MCP server using the standard MCP protocol over stdio, and the server provides 19 distinct tools categorized into user management, domain management, routing management, password reset methods, and billing checks. To use it in your MCP client, configure the server entry with the command npx -y purelymail-mcp-server (or the equivalent environment and path) and supply your PURELYMAIL_API_KEY to authorize requests. The server also supports a mock development mode for safe testing without touching real data.

Example configuration for Claude/Desktop clients shows how to wire the mcpServers entry to run the server via npx, with the API key supplied through environment variables. When using production mode, set PURELYMAIL_API_KEY and start the server with the provided commands, then issue MCP tool calls like create_user, list_domains, or check_account_credit via your client.

Prerequisites

• Node.js 20+ (required for building/running from source)
• npm (comes with Node.js) or pnpm/yarn if you prefer
• PurelyMail API key for production use
• Optional: Nix (for reproducible development environments)

From npm (no install required via npx)

• You can run the server directly with npx:

npx -y purelymail-mcp-server

From source (clone and build)

# Clone the repository
git clone https://github.com/gui-wf/purelymail-mcp-server.git
cd purelymail-mcp-server

# Install dependencies
npm install

# Build the TypeScript project
npm run build

# Run the built server
node dist/index.js

Using Nix (for development or reproducible environments)

nix develop
# Or to run the server via the flake (if configured)
nix run github:gui-wf/purelymail-mcp-server --quiet --refresh

Configure your MCP client with the server entry, for example using npx as shown above, and provide the API key via environment variable PURELYMAIL_API_KEY. The server supports mock mode for development (MOCK_MODE=true) to avoid touching real data.

Tips and common notes:

• Always provide PURELYMAIL_API_KEY in production; omit or unset for mock mode but be aware some endpoints may not be available.
• The server uses a generated TypeScript client from PurelyMail's swagger; this provides type safety for all 19 tools grouped by function (Users, Domains, Routing, Password Reset, Billing).
• Mock mode uses swagger response examples when available and falls back to sensible defaults for missing examples.
• If running via Node.js, you can point to the dist/index.js file after building or rely on the npx shortcut for quick experiments.
• When configuring clients (Claude, Claude Code, or other MCP clients), ensure the environment variable is wired correctly (PURELYMAIL_API_KEY) and that the command/args match your environment (npx vs nix vs node path).
• For production deployments, consider using the provided Nix flake to ensure consistent dependencies across environments.