KeenMail MCP Server

A Model Context Protocol (MCP) server for integrating with the KeenMail API. This server allows AI assistants to send template-based emails through KeenMail's service.

Features

• MCP Compatible: Works with Claude Desktop and other MCP clients
• UVX Ready: Installable and runnable via uvx for easy distribution
• Environment Configuration: Secure API key management through environment variables
• STDIO Transport: Full compatibility with MCP protocol standards
• Template Email Sending: Send emails using KeenMail templates with dynamic data

Installation

Using UVX (Recommended)

uvx keenmail-mcp-server

Using Docker (Recommended for Production)

# Quick start with Docker Compose
git clone https://github.com/optimoz-inc/keenmail-mcp-server.git
cd keenmail-mcp-server
cp .env.docker .env
# Edit .env with your API credentials
docker-compose up -d

Using pip

pip install keenmail-mcp-server

From source

git clone https://github.com/optimoz-inc/keenmail-mcp-server.git
cd keenmail-mcp-server
uv sync --dev
uv run python -m keenmail_mcp

Configuration

Set the following environment variables before running:

export KEENMAIL_API_KEY="your_api_key_here"
export KEENMAIL_SECRET="your_secret_key_here"
export KEENMAIL_PROVIDER_ID="amazonaws"  # Required: Email provider ID
export KEENMAIL_FROM_EMAIL="mcp@optimoz.com"  # Required: Default sender email
export KEENMAIL_BASE_URL="https://app.keenmail.com/api/v1"  # Optional, defaults to this

Environment File (.env)

You can also create a .env file in your working directory:

KEENMAIL_API_KEY=your_api_key_here
KEENMAIL_SECRET=your_secret_key_here
KEENMAIL_PROVIDER_ID=amazonaws
KEENMAIL_FROM_EMAIL=mcp@optimoz.com
KEENMAIL_BASE_URL=https://app.keenmail.com/api/v1

Usage

With Docker (Recommended)

# Development mode
./scripts/docker-run.sh --dev --logs

# Production mode
./scripts/docker-run.sh --prod

# Build and run
./scripts/docker-run.sh --build --logs

With Docker Compose

# Development
cp .env.docker .env
# Edit .env with your credentials
docker-compose up -d

# Production
docker-compose -f docker-compose.prod.yml up -d

# View logs
docker-compose logs -f keenmail-mcp-server

With UVX

# Set environment variables
export KEENMAIL_API_KEY="your_key"
export KEENMAIL_SECRET="your_secret"

# Run the server
uvx keenmail-mcp-server

With Claude Desktop

Add to your Claude Desktop configuration file:

{
  "mcpServers": {
    "keenmail": {
      "command": "uvx",
      "args": ["keenmail-mcp-server"],
      "env": {
        "KEENMAIL_API_KEY": "your_api_key",
        "KEENMAIL_SECRET": "your_secret"
      }
    }
  }
}

Programmatically

from keenmail_mcp import create_server

server = create_server()
server.run(transport="stdio")

Available Tools

The MCP server exposes the following tools:

sendTemplateEmail

Send an email using a KeenMail template.

Parameters:

• templateId (string): The ID of the email template
• providerId (string): The email provider configuration ID
• recipients (array): List of recipient objects with email details and template data

Example:

{
  "templateId": "welcome_email",
  "providerId": "ses_smtp_test",
  "recipients": [
    {
      "from": "mcp@optimoz.com",
      "to": "renesa@optimoz.com",
      "data": {
        "userName": "John Doe",
        "companyName": "Example Corp"
      }
    }
  ]
}

Development

Requirements

• Python 3.10+
• uv (recommended) or pip

Setup

# Clone the repository
git clone https://github.com/optimoz-inc/keenmail-mcp-server.git
cd keenmail-mcp-server

# Install dependencies with uv
uv sync --dev

# Or with pip
pip install -e ".[dev]"

Running Tests

uv run pytest

Linting and Formatting

# Run ruff linter
uv run ruff check .

# Format code
uv run ruff format .

# Type checking
uv run mypy src/

Building

Python Package

uv build

Docker Image

# Quick build
./scripts/docker-build.sh

# Build with specific tag
./scripts/docker-build.sh --tag v0.1.3

# Multi-platform build and push
./scripts/docker-build.sh --platform linux/amd64,linux/arm64 --push --tag v0.1.3

Publishing

This package uses automated publishing through GitHub Actions:

1. Create a version tag:

   # Update version in pyproject.toml first, then:
   uv version patch  # or minor, major
   git add .
   git commit -m "Bump version to $(uv version --dry-run patch)"
   git tag "v$(grep version pyproject.toml | cut -d'"' -f2)"
   git push origin main --tags
   

2. Automatic publishing: The GitHub Action will automatically build and publish to PyPI when a version tag is pushed.

Manual Publishing

Python Package

# Build the package
uv build

# Publish to PyPI
uv publish

Docker Image

# Build and push to GitHub Container Registry
./scripts/docker-build.sh --push --tag v0.1.3

# Or manually with Docker
docker build -t ghcr.io/optimoz-inc/keenmail-mcp-server:v0.1.3 .
docker push ghcr.io/optimoz-inc/keenmail-mcp-server:v0.1.3

Docker Deployment

Quick Start

1. Clone the repository:

   git clone https://github.com/optimoz-inc/keenmail-mcp-server.git
   cd keenmail-mcp-server
   

2. Set up environment:

   cp .env.docker .env
   # Edit .env with your KeenMail API credentials
   

3. Run with Docker Compose:

   # Development
   docker-compose up -d
   
   # Production
   docker-compose -f docker-compose.prod.yml up -d
   

Production Deployment

The production Docker setup includes:

• Security hardening with non-root user and read-only filesystem
• Resource limits and health checks
• Log rotation and structured logging
• Restart policies for high availability
• Network isolation with custom bridge network

# Production deployment
cp .env.docker .env
# Configure production credentials
docker-compose -f docker-compose.prod.yml up -d

# Monitor
docker-compose -f docker-compose.prod.yml ps
docker-compose -f docker-compose.prod.yml logs -f

Container Registry

Images are automatically published to GitHub Container Registry:

• ghcr.io/optimoz-inc/keenmail-mcp-server:latest - Latest development build
• ghcr.io/optimoz-inc/keenmail-mcp-server:v0.1.3 - Specific version tags

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• GitHub Issues: Create an issue
• KeenMail Support: support@keenmail.com
• Organization: Optimoz, Inc.