# 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)
```bash
uvx keenmail-mcp-server
```
### Using Docker (Recommended for Production)
```bash
# 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
```bash
pip install keenmail-mcp-server
```
### From source
```bash
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:
```bash
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:
```bash
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)
```bash
# 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
```bash
# 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
```bash
# 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:
```json
{
"mcpServers": {
"keenmail": {
"command": "uvx",
"args": ["keenmail-mcp-server"],
"env": {
"KEENMAIL_API_KEY": "your_api_key",
"KEENMAIL_SECRET": "your_secret"
}
}
}
}
```
### Programmatically
```python
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:**
```json
{
"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
```bash
# 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
```bash
uv run pytest
```
### Linting and Formatting
```bash
# Run ruff linter
uv run ruff check .
# Format code
uv run ruff format .
# Type checking
uv run mypy src/
```
### Building
#### Python Package
```bash
uv build
```
#### Docker Image
```bash
# 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:**
```bash
# 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
```bash
# Build the package
uv build
# Publish to PyPI
uv publish
```
#### Docker Image
```bash
# 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:**
```bash
git clone https://github.com/optimoz-inc/keenmail-mcp-server.git
cd keenmail-mcp-server
```
2. **Set up environment:**
```bash
cp .env.docker .env
# Edit .env with your KeenMail API credentials
```
3. **Run with Docker Compose:**
```bash
# 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
```bash
# 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](https://github.com/optimoz-inc/keenmail-mcp-server/issues)
- KeenMail Support: support@keenmail.com
- Organization: [Optimoz, Inc.](https://optimoz.com)
Raw data
{
"_id": null,
"home_page": null,
"name": "keenmail-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "api, email, keenmail, mcp, server",
"author": null,
"author_email": "Renesa Patel <renesa@optimoz.com>",
"download_url": "https://files.pythonhosted.org/packages/0d/ca/c6811b936ce91b86ec57722c807771ac342bdfb61d4549f124cbbaf81134/keenmail_mcp_server-0.1.6.tar.gz",
"platform": null,
"description": "# KeenMail MCP Server\n\nA 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.\n\n## Features\n\n- **MCP Compatible**: Works with Claude Desktop and other MCP clients\n- **UVX Ready**: Installable and runnable via `uvx` for easy distribution\n- **Environment Configuration**: Secure API key management through environment variables\n- **STDIO Transport**: Full compatibility with MCP protocol standards\n- **Template Email Sending**: Send emails using KeenMail templates with dynamic data\n\n## Installation\n\n### Using UVX (Recommended)\n\n```bash\nuvx keenmail-mcp-server\n```\n\n### Using Docker (Recommended for Production)\n\n```bash\n# Quick start with Docker Compose\ngit clone https://github.com/optimoz-inc/keenmail-mcp-server.git\ncd keenmail-mcp-server\ncp .env.docker .env\n# Edit .env with your API credentials\ndocker-compose up -d\n```\n\n### Using pip\n\n```bash\npip install keenmail-mcp-server\n```\n\n### From source\n\n```bash\ngit clone https://github.com/optimoz-inc/keenmail-mcp-server.git\ncd keenmail-mcp-server\nuv sync --dev\nuv run python -m keenmail_mcp\n```\n\n## Configuration\n\nSet the following environment variables before running:\n\n```bash\nexport KEENMAIL_API_KEY=\"your_api_key_here\"\nexport KEENMAIL_SECRET=\"your_secret_key_here\"\nexport KEENMAIL_PROVIDER_ID=\"amazonaws\" # Required: Email provider ID\nexport KEENMAIL_FROM_EMAIL=\"mcp@optimoz.com\" # Required: Default sender email\nexport KEENMAIL_BASE_URL=\"https://app.keenmail.com/api/v1\" # Optional, defaults to this\n```\n\n### Environment File (.env)\n\nYou can also create a `.env` file in your working directory:\n\n```bash\nKEENMAIL_API_KEY=your_api_key_here\nKEENMAIL_SECRET=your_secret_key_here\nKEENMAIL_PROVIDER_ID=amazonaws\nKEENMAIL_FROM_EMAIL=mcp@optimoz.com\nKEENMAIL_BASE_URL=https://app.keenmail.com/api/v1\n```\n\n## Usage\n\n### With Docker (Recommended)\n\n```bash\n# Development mode\n./scripts/docker-run.sh --dev --logs\n\n# Production mode\n./scripts/docker-run.sh --prod\n\n# Build and run\n./scripts/docker-run.sh --build --logs\n```\n\n### With Docker Compose\n\n```bash\n# Development\ncp .env.docker .env\n# Edit .env with your credentials\ndocker-compose up -d\n\n# Production\ndocker-compose -f docker-compose.prod.yml up -d\n\n# View logs\ndocker-compose logs -f keenmail-mcp-server\n```\n\n### With UVX\n\n```bash\n# Set environment variables\nexport KEENMAIL_API_KEY=\"your_key\"\nexport KEENMAIL_SECRET=\"your_secret\"\n\n# Run the server\nuvx keenmail-mcp-server\n```\n\n### With Claude Desktop\n\nAdd to your Claude Desktop configuration file:\n\n```json\n{\n \"mcpServers\": {\n \"keenmail\": {\n \"command\": \"uvx\",\n \"args\": [\"keenmail-mcp-server\"],\n \"env\": {\n \"KEENMAIL_API_KEY\": \"your_api_key\",\n \"KEENMAIL_SECRET\": \"your_secret\"\n }\n }\n }\n}\n```\n\n### Programmatically\n\n```python\nfrom keenmail_mcp import create_server\n\nserver = create_server()\nserver.run(transport=\"stdio\")\n```\n\n## Available Tools\n\nThe MCP server exposes the following tools:\n\n### `sendTemplateEmail`\n\nSend an email using a KeenMail template.\n\n**Parameters:**\n- `templateId` (string): The ID of the email template\n- `providerId` (string): The email provider configuration ID\n- `recipients` (array): List of recipient objects with email details and template data\n\n**Example:**\n```json\n{\n \"templateId\": \"welcome_email\",\n \"providerId\": \"ses_smtp_test\",\n \"recipients\": [\n {\n \"from\": \"mcp@optimoz.com\",\n \"to\": \"renesa@optimoz.com\",\n \"data\": {\n \"userName\": \"John Doe\",\n \"companyName\": \"Example Corp\"\n }\n }\n ]\n}\n```\n\n## Development\n\n### Requirements\n\n- Python 3.10+\n- uv (recommended) or pip\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/optimoz-inc/keenmail-mcp-server.git\ncd keenmail-mcp-server\n\n# Install dependencies with uv\nuv sync --dev\n\n# Or with pip\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\nuv run pytest\n```\n\n### Linting and Formatting\n\n```bash\n# Run ruff linter\nuv run ruff check .\n\n# Format code\nuv run ruff format .\n\n# Type checking\nuv run mypy src/\n```\n\n### Building\n\n#### Python Package\n```bash\nuv build\n```\n\n#### Docker Image\n```bash\n# Quick build\n./scripts/docker-build.sh\n\n# Build with specific tag\n./scripts/docker-build.sh --tag v0.1.3\n\n# Multi-platform build and push\n./scripts/docker-build.sh --platform linux/amd64,linux/arm64 --push --tag v0.1.3\n```\n\n## Publishing\n\nThis package uses automated publishing through GitHub Actions:\n\n1. **Create a version tag:**\n ```bash\n # Update version in pyproject.toml first, then:\n uv version patch # or minor, major\n git add .\n git commit -m \"Bump version to $(uv version --dry-run patch)\"\n git tag \"v$(grep version pyproject.toml | cut -d'\"' -f2)\"\n git push origin main --tags\n ```\n\n2. **Automatic publishing:** The GitHub Action will automatically build and publish to PyPI when a version tag is pushed.\n\n### Manual Publishing\n\n#### Python Package\n```bash\n# Build the package\nuv build\n\n# Publish to PyPI\nuv publish\n```\n\n#### Docker Image\n```bash\n# Build and push to GitHub Container Registry\n./scripts/docker-build.sh --push --tag v0.1.3\n\n# Or manually with Docker\ndocker build -t ghcr.io/optimoz-inc/keenmail-mcp-server:v0.1.3 .\ndocker push ghcr.io/optimoz-inc/keenmail-mcp-server:v0.1.3\n```\n\n## Docker Deployment\n\n### Quick Start\n\n1. **Clone the repository:**\n ```bash\n git clone https://github.com/optimoz-inc/keenmail-mcp-server.git\n cd keenmail-mcp-server\n ```\n\n2. **Set up environment:**\n ```bash\n cp .env.docker .env\n # Edit .env with your KeenMail API credentials\n ```\n\n3. **Run with Docker Compose:**\n ```bash\n # Development\n docker-compose up -d\n \n # Production\n docker-compose -f docker-compose.prod.yml up -d\n ```\n\n### Production Deployment\n\nThe production Docker setup includes:\n- **Security hardening** with non-root user and read-only filesystem\n- **Resource limits** and health checks\n- **Log rotation** and structured logging\n- **Restart policies** for high availability\n- **Network isolation** with custom bridge network\n\n```bash\n# Production deployment\ncp .env.docker .env\n# Configure production credentials\ndocker-compose -f docker-compose.prod.yml up -d\n\n# Monitor\ndocker-compose -f docker-compose.prod.yml ps\ndocker-compose -f docker-compose.prod.yml logs -f\n```\n\n### Container Registry\n\nImages are automatically published to GitHub Container Registry:\n- `ghcr.io/optimoz-inc/keenmail-mcp-server:latest` - Latest development build\n- `ghcr.io/optimoz-inc/keenmail-mcp-server:v0.1.3` - Specific version tags\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Support\n\nFor issues and questions:\n- GitHub Issues: [Create an issue](https://github.com/optimoz-inc/keenmail-mcp-server/issues)\n- KeenMail Support: support@keenmail.com\n- Organization: [Optimoz, Inc.](https://optimoz.com)",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for KeenMail API integration",
"version": "0.1.6",
"project_urls": {
"Homepage": "https://github.com/optimoz-inc/keenmail-mcp-server",
"Issues": "https://github.com/optimoz-inc/keenmail-mcp-server/issues",
"Organization": "https://optimoz.com",
"Repository": "https://github.com/optimoz-inc/keenmail-mcp-server"
},
"split_keywords": [
"api",
" email",
" keenmail",
" mcp",
" server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7aa2d400cf4ac0b1b93e75cfa8ff5d1f6a9ea605c63661ec3463740500982631",
"md5": "0a1bb9b484dfaa55d787c4ca9c7f3ed1",
"sha256": "fc51091d7d15ab13605ff1ade864c2ea9d75e20cc1ed8bd801da48f158656aec"
},
"downloads": -1,
"filename": "keenmail_mcp_server-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0a1bb9b484dfaa55d787c4ca9c7f3ed1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 10724,
"upload_time": "2025-08-22T22:25:08",
"upload_time_iso_8601": "2025-08-22T22:25:08.553304Z",
"url": "https://files.pythonhosted.org/packages/7a/a2/d400cf4ac0b1b93e75cfa8ff5d1f6a9ea605c63661ec3463740500982631/keenmail_mcp_server-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0dcac6811b936ce91b86ec57722c807771ac342bdfb61d4549f124cbbaf81134",
"md5": "bd91361bf706c354f2837a56b6de9925",
"sha256": "771d9e79f4d7ad3fc436da7256e3104b8a5b9599f00a73214e4bb221cb430805"
},
"downloads": -1,
"filename": "keenmail_mcp_server-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "bd91361bf706c354f2837a56b6de9925",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 100049,
"upload_time": "2025-08-22T22:25:09",
"upload_time_iso_8601": "2025-08-22T22:25:09.681434Z",
"url": "https://files.pythonhosted.org/packages/0d/ca/c6811b936ce91b86ec57722c807771ac342bdfb61d4549f124cbbaf81134/keenmail_mcp_server-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 22:25:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "optimoz-inc",
"github_project": "keenmail-mcp-server",
"github_not_found": true,
"lcname": "keenmail-mcp-server"
}
JSON
