PurelyMail MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@PurelyMail MCP Server list all users under my account"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-serverOr use Nix (via GitHub flake):
nix run github:gui-wf/purelymail-mcp-server --quiet --refreshConfigure 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 inspector3. 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.jsMCP Integration
Claude Desktop
Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):
Using npx (recommended - no installation):
{
"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 userdelete_user- Delete an email userlist_users- List all users under your accountmodify_user- Modify user settingsget_user- Retrieve user detailscreate_app_password- Create an app-specific passworddelete_app_password- Delete an app password
Password Reset Management
create_or_update_password_reset_method- Create or update password reset methoddelete_password_reset_method- Delete a password reset methodlist_password_reset_methods- List all password reset methods for a user
Domain Management
add_domain- Add a new domainlist_domains- List all domainsupdate_domain_settings- Update domain settingsdelete_domain- Delete a domainget_ownership_code- Get DNS ownership verification code
Routing Management
create_routing_rule- Create a new routing ruledelete_routing_rule- Delete a routing rulelist_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
Via npx (Recommended - No Installation)
npx -y purelymail-mcp-serverVia Nix (GitHub Flake)
nix run github:gui-wf/purelymail-mcp-server --quiet --refreshFrom 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 buildTool 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:
Development Guide - Development workflow and contributing guidelines
API Updates - Keeping the server synchronized with PurelyMail API changes
Troubleshooting - Common issues and solutions
Publishing
Releases go through GitHub Actions Trusted Publisher (OIDC). No NPM_TOKEN in CI.
Bump
versioninpackage.json(and flake if needed).Merge to
master.Tag and push:
git tag vX.Y.Z && git push origin vX.Y.ZWorkflow
.github/workflows/publish-npm.ymlpublishes 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 toolsadd_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
Scored across 19 tools
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.
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.
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.
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
Related MCP Connectors
Send email, manage domains, templates, webhooks and broadcasts from your AI agent.
Send email, manage domains, templates, webhooks and broadcasts from your AI agent.
Email hosting from your AI: read and send mail, add domains, check DNS and manage mailboxes.
Email for AI agents — send, receive as a webhook, manage domains, templates, routing.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to manage Migadu email hosting services through natural language, including creating mailboxes, setting up aliases, configuring autoresponders, and handling bulk operations efficiently.3531 PyPI17MIT
- AlicenseNot gradedqualityDmaintenanceProvides AI assistants with the ability to manage email accounts through cPanel's UAPI, enabling automated email account creation, deletion, configuration, and forwarding management.3MIT
- AlicenseCqualityDmaintenanceEnables 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.100298 npm3MIT
- AlicenseBqualityCmaintenanceEnables 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.142Apache 2.0