Skip to main content
Glama
PurelyMail MCP Server

PurelyMail MCP Server

by gui-wf

PurelyMail MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to PurelyMail's email management API.

Usage

Run with npx (no installation needed):

npx -y purelymail-mcp-server

Or use Nix (via GitHub flake):

nix run github:gui-wf/purelymail-mcp-server --quiet --refresh

Configure in your MCP client:

{
  "mcpServers": {
    "purelymail": {
      "command": "npx",
      "args": ["-y", "purelymail-mcp-server"],
      "env": {
        "PURELYMAIL_API_KEY": "your-api-key-here"
      }
    }
  }
}

Related MCP server: cPanel MCP Server

Features

  • Type-Safe API Integration: Generated TypeScript client from PurelyMail's swagger specification

  • Comprehensive Tool Coverage: Manage users, domains, routing rules, billing, and password reset methods

  • Mock Development Mode: Test and develop safely without touching real data

  • One Tool Per Operation: Each OpenAPI operation becomes its own MCP tool (e.g. list_domains, create_user)

  • Error Handling: Robust error reporting and validation

Quick Start

1. Prerequisites

  • Node.js 20+ (if installing from source)

  • PurelyMail API key (for production use)

  • Nix (for reproducible development environment - source only)

2. Testing with Mock Data

# Run in mock mode (no API key required)
MOCK_MODE=true npm run dev

# Test with MCP Inspector
MOCK_MODE=true npm run inspector

3. Production Setup

# Set your PurelyMail API key
export PURELYMAIL_API_KEY="your-api-key-here"

# Run the server
npm run dev

# Or build and run
npm run build
node dist/index.js

MCP Integration

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "purelymail": {
      "command": "npx",
      "args": ["-y", "purelymail-mcp-server"],
      "env": {
        "PURELYMAIL_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using Nix from GitHub:

{
  "mcpServers": {
    "purelymail": {
      "command": "nix",
      "args": ["run", "github:gui-wf/purelymail-mcp-server", "--quiet", "--refresh"],
      "env": {
        "PURELYMAIL_API_KEY": "your-api-key-here"
      }
    }
  }
}

When using from source with Nix:

{
  "mcpServers": {
    "purelymail": {
      "command": "nix",
      "args": ["run", "/path/to/purelymail-mcp-server#default"],
      "env": {
        "PURELYMAIL_API_KEY": "your-api-key-here"
      }
    }
  }
}

When using from source with Node.js:

{
  "mcpServers": {
    "purelymail": {
      "command": "node",
      "args": ["/path/to/purelymail-mcp-server/dist/index.js"],
      "env": {
        "PURELYMAIL_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code

For Claude Code, create a .mcp.json file in your project root:

{
  "mcpServers": {
    "purelymail": {
      "command": "npx",
      "args": ["-y", "purelymail-mcp-server"],
      "env": {
        "PURELYMAIL_API_KEY": "${PURELYMAIL_API_KEY}"
      }
    }
  }
}

Other MCP Clients

The server uses stdio transport and follows the MCP specification, making it compatible with any MCP-compliant client.

Available Tools

The server provides 19 individual tools, each corresponding to a specific PurelyMail API operation:

User Management

  • create_user - Create a new email user

  • delete_user - Delete an email user

  • list_users - List all users under your account

  • modify_user - Modify user settings

  • get_user - Retrieve user details

  • create_app_password - Create an app-specific password

  • delete_app_password - Delete an app password

Password Reset Management

  • create_or_update_password_reset_method - Create or update password reset method

  • delete_password_reset_method - Delete a password reset method

  • list_password_reset_methods - List all password reset methods for a user

Domain Management

  • add_domain - Add a new domain

  • list_domains - List all domains

  • update_domain_settings - Update domain settings

  • delete_domain - Delete a domain

  • get_ownership_code - Get DNS ownership verification code

Routing Management

  • create_routing_rule - Create a new routing rule

  • delete_routing_rule - Delete a routing rule

  • list_routing_rules - List all routing rules

Billing

  • check_account_credit - Check current account credit balance

Features

  • Type-Safe API Integration: Generated TypeScript client from PurelyMail's swagger specification

  • Comprehensive Tool Coverage: Manage users, domains, routing rules, billing, and password reset methods

  • Mock Development Mode: Test and develop safely without touching real data

  • One Tool Per Operation: Each OpenAPI operation becomes its own MCP tool (e.g. list_domains, create_user)

  • Error Handling: Robust error reporting and validation

Installation

npx -y purelymail-mcp-server

Via Nix (GitHub Flake)

nix run github:gui-wf/purelymail-mcp-server --quiet --refresh

From Source

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

# Using Nix (recommended)
nix develop

# Or use npm directly
npm install

# Build the TypeScript project
npm run build

Tool Usage Patterns

Example: Creating a User

{
  "tool": "create_user",
  "arguments": {
    "userName": "john",
    "domainName": "example.com",
    "password": "secure-password",
    "enableSearchIndexing": true,
    "sendWelcomeEmail": true
  }
}

Example: Listing Domains

{
  "tool": "list_domains",
  "arguments": {
    "includeShared": false
  }
}

Example: Getting User Details

{
  "tool": "get_user",
  "arguments": {
    "userName": "john@example.com"
  }
}

Architecture Notes

Type Safety

  • All API interactions use generated TypeScript types

  • Zero manual type definitions - everything derives from swagger spec

  • Automatic validation and error handling

Mock vs Real API

  • Mock mode uses swagger response examples when available

  • Fallback to sensible defaults for missing examples

  • Same interface for both modes ensures consistent behavior

Error Handling

  • Structured error responses with context

  • API errors are wrapped and formatted for AI consumption

  • Network and validation errors are handled gracefully

Documentation

See docs/ for project documentation:

Publishing

Releases go through GitHub Actions Trusted Publisher (OIDC). No NPM_TOKEN in CI.

  1. Bump version in package.json (and flake if needed).

  2. Merge to master.

  3. Tag and push: git tag vX.Y.Z && git push origin vX.Y.Z

  4. Workflow .github/workflows/publish-npm.yml publishes to npm.

Local/manual publish still needs NPM_TOKEN because the repo .npmrc uses ${NPM_TOKEN} (overrides npm login in this directory).

License

This project is licensed under MIT license - see the LICENSE file for details.

Dependencies

This project uses MIT and Apache-2.0 licensed dependencies. See docs/package-licenses.md for full dependency licensing information.

Available Tools

19 tools
add_domainC

Adds a domain.. Adds a domain, assuming it passes DNS checks.

Inputs: domainName (required).

check_account_creditC

Returns current account credit.. Returns current account credit, as a BigDecimal string with precision 64.

Inputs: no named parameters.

create_app_passwordC

Creates an app password. Creates a new app password.

Inputs: userHandle (required), name.

create_or_update_password_reset_methodC

Creates or updates a password reset method (either phone or email).

Inputs: type (required), target (required), userName (required), description, +2 more.

create_routing_ruleB

Creates a new routing rule for a domain. Routing rule must not have the same user/prefix as any other existing rules for the domain.

Inputs: prefix (required), matchUser (required), domainName (required), targetAddresses (required), +1 more.

create_userD

Creates a user. Creates a new user.

Inputs: password (required), userName (required), domainName (required), recoveryEmail, +6 more.

delete_app_passwordC

Deletes app password. Deletes an app password.

Inputs: userName (required), appPassword (required).

delete_domainB

Delete Domain. Deletes a domain, and all dependent settings and users.

Inputs: name (required).

delete_password_reset_methodC

Deletes a password reset method.

Inputs: userName (required), target.

delete_routing_ruleC

Deletes an existing routing rule

Inputs: routingRuleId (required).

delete_userC

Deletes a user. Deletes a user.

Inputs: userName (required).

get_ownership_codeA

Gets ownership code record. Gets the DNS record value of the Purelymail ownership proof record, required to add a domain

Inputs: no named parameters.

get_userC

Gets a user. Retrieves details of a user.

Inputs: userName (required).

list_domainsC

Lists domains accessible to an account.. Lists domains accessible to an account, possibly including shared domains.

Inputs: includeShared.

list_password_reset_methodsC

Lists all password reset methods for a user.

Inputs: userName (required).

list_routing_rulesA

Lists all routing rules active under your account

Inputs: no named parameters.

list_usersC

Lists all users under your account.. Lists all users under your account (up to 1000).

Inputs: no named parameters.

modify_userD

Modifies a user. Modifies a user.

Inputs: userName (required), newPassword, newUserName, enablePasswordReset, +2 more.

update_domain_settingsC

Updates settings for a domain. Updates settings for an existing owned domain.

Inputs: name (required), recheckDns, allowAccountReset, symbolicSubaddressing.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 19 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: users, domains, routing rules, password reset methods, app passwords, ownership proof, and account credit are clearly separated. No two tools appear to perform the same operation.

    Naming Consistency4/5

    Most tools follow a readable snake_case verb_noun pattern with consistent pluralization. Minor deviations exist in verb choices such as add_domain vs create_user, modify_user vs update_domain_settings, and check_account_credit vs get_user.

    Tool Count3/5

    Nineteen tools is somewhat heavy for an account administration surface, and the count is driven by several small resource groups. Most tools are justified, but it sits at the upper end of what feels comfortably scoped.

    Completeness4/5

    Core resources have solid coverage: users have full CRUD, domains have add/list/update/delete, and routing rules plus password reset methods have create/delete/list operations. Minor gaps exist, such as no list_app_passwords and no direct update for routing rules, though most can be worked around.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to manage Migadu email hosting services through natural language, including creating mailboxes, setting up aliases, configuring autoresponders, and handling bulk operations efficiently.
      35
      31 PyPI
      17
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI assistants with the ability to manage email accounts through cPanel's UAPI, enabling automated email account creation, deletion, configuration, and forwarding management.
      3
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      Enables AI assistants to interact with the Zapmail API through natural language commands for domain management, mailbox operations, and exports to third-party platforms like Reachinbox and Instantly. Provides complete coverage of 46+ Zapmail tools with dynamic API integration and multi-workspace support.
      100
      298 npm
      3
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to interact with the Inbound Email API to manage domains, endpoints, and email communications. Users can send or schedule emails, manage webhooks, and retrieve email threads through natural language commands.
      14
      2
      Apache 2.0