# Stalwart Mail MCP Server

**Date:** 2026-02-02 15:30
**Context:** Created MCP server for managing Stalwart mail server via Claude Code

## Server Location

```
~/mcp-servers/stalwart-mail/
├── server.py          # MCP server implementation
├── requirements.txt   # Python dependencies
├── pyproject.toml     # Project configuration
├── README.md          # Documentation
└── .venv/             # Python virtual environment (3.12)
```

## Configuration

Added to Claude Code with:
```bash
claude mcp add stalwart-mail \
  -e STALWART_URL=http://192.168.1.3:8081 \
  -e STALWART_USER=admin \
  -e STALWART_PASS=QfKYjCJdxu \
  --scope user \
  -- /Users/agutierrez/mcp-servers/stalwart-mail/.venv/bin/python \
     /Users/agutierrez/mcp-servers/stalwart-mail/server.py
```

## Available Tools

### User Management
| Tool | Description |
|------|-------------|
| `list_users` | List all mail users and domains |
| `get_user` | Get detailed user information |
| `create_user` | Create new mail users |
| `update_user_password` | Change user passwords |
| `delete_user` | Remove users |
| `add_email_alias` | Add email aliases |

### Domain Management
| Tool | Description |
|------|-------------|
| `create_domain` | Add new email domains |
| `generate_dkim` | Generate DKIM keys |

### Queue Management
| Tool | Description |
|------|-------------|
| `list_queue` | View pending messages |
| `get_queue_status` | Check queue status |
| `delete_queued_message` | Cancel message delivery |
| `retry_queued_message` | Retry failed deliveries |

### Monitoring
| Tool | Description |
|------|-------------|
| `get_metrics` | Server performance metrics |
| `get_dmarc_reports` | Email authentication reports |
| `get_server_logs` | Recent log entries |

### Troubleshooting
| Tool | Description |
|------|-------------|
| `check_dns_records` | Verify domain DNS setup |
| `troubleshoot_delivery` | Diagnose delivery issues |

### Spam Filter
| Tool | Description |
|------|-------------|
| `train_spam` | Mark messages as spam |
| `train_ham` | Mark messages as legitimate |
| `update_spam_filter` | Update filter definitions |

## Usage Examples

After restarting Claude Code:

```
"List all mail users"
"Create user john with email john@whyrating.com password Secret123"
"Check the mail queue"
"Verify DNS records for whyrating.com"
"Show server metrics"
```

## API Reference

Based on Stalwart's REST Management API:
- Overview: https://stalw.art/docs/api/management/overview/
- Endpoints: https://stalw.art/docs/api/management/endpoints/

## Related

- Stalwart Admin: http://192.168.1.3:8081
- Snappymail: http://192.168.1.3:8082
- Previous setup: .artifacts/2026-02-02_15-20_whyrating-email-setup.md