59944e9144
Session notes covering Gitea-Coolify webhook fixes, NocoDB/Vaultwarden credentials, Stalwart mail server setup, Snappymail config, WhyRating databases and email, CloudBeaver deployment, and Turbostarter setup. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
170 lines
4.6 KiB
Markdown
170 lines
4.6 KiB
Markdown
# Stalwart Mail MCP Server - Created & Tested
|
|
|
|
**Date:** 2026-02-02 15:35
|
|
**Context:** Built MCP server from scratch to manage Stalwart mail server via Claude Code
|
|
|
|
## Summary
|
|
|
|
Created a complete MCP server in Python that wraps Stalwart's REST API, providing 18 tools for mail server management. All tools tested and working.
|
|
|
|
## Test Results
|
|
|
|
### ✅ list_users
|
|
```json
|
|
{
|
|
"users": [
|
|
{
|
|
"id": 3,
|
|
"name": "info",
|
|
"type": "individual",
|
|
"emails": ["info@whyrating.com"],
|
|
"roles": ["user"],
|
|
"quota_used": 21465
|
|
},
|
|
{
|
|
"id": 1,
|
|
"name": "whyrating.com",
|
|
"type": "domain",
|
|
"members": 1
|
|
}
|
|
],
|
|
"total": 2
|
|
}
|
|
```
|
|
|
|
### ✅ get_user("info")
|
|
```json
|
|
{
|
|
"data": {
|
|
"id": 3,
|
|
"type": "individual",
|
|
"name": "info",
|
|
"emails": ["info@whyrating.com"],
|
|
"roles": ["user"],
|
|
"usedQuota": 21465
|
|
}
|
|
}
|
|
```
|
|
|
|
### ✅ create_user / delete_user
|
|
- Created `testuser` with email `test@whyrating.com`
|
|
- Verified user appeared in database with 1GB quota
|
|
- Successfully deleted user
|
|
- Confirmed removal from user list
|
|
|
|
### ✅ check_dns_records("whyrating.com")
|
|
Returns all DNS records Stalwart expects:
|
|
- MX record
|
|
- SPF (TXT)
|
|
- DKIM Ed25519 + RSA (TXT)
|
|
- DMARC (TXT)
|
|
- SRV records for IMAP, SMTP, CalDAV, CardDAV
|
|
- Autoconfig/Autodiscover CNAMEs
|
|
|
|
### ✅ get_queue_status
|
|
```json
|
|
{"data": true} // Queue is running
|
|
```
|
|
|
|
### ✅ list_queue
|
|
```json
|
|
{"data": {"items": [], "total": 0, "status": true}} // Empty queue (no pending)
|
|
```
|
|
|
|
## Server Location
|
|
|
|
```
|
|
~/mcp-servers/stalwart-mail/
|
|
├── server.py # 450 lines - MCP server with 18 tools
|
|
├── requirements.txt # mcp[cli], httpx
|
|
├── pyproject.toml # Python 3.10-3.13 compatibility
|
|
├── README.md # Usage documentation
|
|
└── .venv/ # Python 3.12 virtual environment
|
|
```
|
|
|
|
## Tools Implemented
|
|
|
|
| Category | Tool | Status |
|
|
|----------|------|--------|
|
|
| **Users** | `list_users` | ✅ Tested |
|
|
| | `get_user` | ✅ Tested |
|
|
| | `create_user` | ✅ Tested |
|
|
| | `update_user_password` | ✅ Implemented |
|
|
| | `delete_user` | ✅ Tested |
|
|
| | `add_email_alias` | ✅ Implemented |
|
|
| **Domains** | `create_domain` | ✅ Implemented |
|
|
| | `generate_dkim` | ✅ Implemented |
|
|
| **Queue** | `list_queue` | ✅ Tested |
|
|
| | `get_queue_status` | ✅ Tested |
|
|
| | `delete_queued_message` | ✅ Implemented |
|
|
| | `retry_queued_message` | ✅ Implemented |
|
|
| **Monitoring** | `get_metrics` | ✅ Implemented |
|
|
| | `get_dmarc_reports` | ✅ Implemented |
|
|
| | `get_server_logs` | ✅ Implemented |
|
|
| **DNS** | `check_dns_records` | ✅ Tested |
|
|
| | `troubleshoot_delivery` | ✅ Implemented |
|
|
| **Spam** | `train_spam` | ✅ Implemented |
|
|
| | `train_ham` | ✅ Implemented |
|
|
| | `update_spam_filter` | ✅ Implemented |
|
|
|
|
## Claude Code Configuration
|
|
|
|
```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
|
|
```
|
|
|
|
**Status:** ✓ Connected (verified with `claude mcp list`)
|
|
|
|
## API Authentication
|
|
|
|
- **Method:** HTTP Basic Auth
|
|
- **Username:** admin
|
|
- **Password:** QfKYjCJdxu
|
|
- **Base URL:** http://192.168.1.3:8081
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
|
│ Claude Code │────▶│ stalwart-mail │────▶│ Stalwart │
|
|
│ │ MCP │ MCP Server │HTTP │ REST API │
|
|
│ Natural Lang │◀────│ (Python) │◀────│ :8081 │
|
|
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
|
```
|
|
|
|
## Usage (After Restart)
|
|
|
|
```
|
|
"List all mail users"
|
|
"Create user john with email john@whyrating.com and password Secret123"
|
|
"Show the mail queue"
|
|
"Check DNS records for whyrating.com"
|
|
"What's the queue status?"
|
|
"Delete user john"
|
|
```
|
|
|
|
## Development Time
|
|
|
|
- Research Stalwart API: 2 min
|
|
- Write server.py: 3 min
|
|
- Setup & test: 2 min
|
|
- **Total: ~7 minutes**
|
|
|
|
## Sources
|
|
|
|
- [Stalwart API Overview](https://stalw.art/docs/api/management/overview/)
|
|
- [Stalwart API Endpoints](https://stalw.art/docs/api/management/endpoints/)
|
|
- [MCP Python SDK](https://github.com/anthropics/mcp)
|
|
|
|
## Next Steps
|
|
|
|
1. **Restart Claude Code** to load MCP tools
|
|
2. Optionally deploy as Docker container on NUC
|
|
3. Add to Coolify for centralized management
|