nuc/docs/mcp-configs.md

# MCP Server Configurations

Detailed setup and configuration guides for MCP servers used with the NUC.

## Stalwart Mail MCP

**Location:** `~/mcp-servers/stalwart-mail/`

Manage the self-hosted Stalwart mail server via natural language.

### Available Tools

| Category | Tools |
|----------|-------|
| **Users** | `list_users`, `get_user`, `create_user`, `update_user_password`, `delete_user`, `add_email_alias` |
| **Domains** | `create_domain`, `generate_dkim` |
| **Queue** | `list_queue`, `get_queue_status`, `delete_queued_message`, `retry_queued_message` |
| **Monitoring** | `get_metrics`, `get_dmarc_reports`, `get_server_logs` |
| **DNS** | `check_dns_records`, `troubleshoot_delivery` |
| **Spam** | `train_spam`, `train_ham`, `update_spam_filter` |

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

### Direct API Test (if MCP not responding)
```bash
curl -s -u "admin:QfKYjCJdxu" "http://192.168.1.3:8081/api/principal" | jq .
```

### Reconfigure MCP
```bash
claude mcp remove stalwart-mail
claude mcp add stalwart-mail \
  -e STALWART_URL=http://192.168.1.3:8081 \
  -e STALWART_USER=admin \
  -e STALWART_PASS=QfKYjCJdxu \
  --scope user \
  -- ~/mcp-servers/stalwart-mail/.venv/bin/python ~/mcp-servers/stalwart-mail/server.py
```

### SMTP Authentication Requirements

1. **Password format:** Must be SHA-512 hashed (not plaintext). When creating users via API:
   ```python
   import crypt
   hashed = crypt.crypt('password', crypt.mksalt(crypt.METHOD_SHA512))
   # Use hashed value in 'secrets' field
   ```
2. **SMTP login:** Use username only (e.g., `info`), NOT full email (`info@whyrating.com`)
3. **Port 465 (SMTPS):** Supports PLAIN/LOGIN auth with implicit TLS
4. **Port 587 (Submission):** Requires STARTTLS, only OAuth supported without TLS

### Send email via Python (from NUC)
```python
import smtplib, ssl
from email.mime.text import MIMEText

context = ssl.create_default_context()
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE

with smtplib.SMTP_SSL('localhost', 465, context=context) as server:
    server.login('info', 'whyrating2026')  # Username only!
    server.sendmail('info@whyrating.com', 'recipient@example.com', msg.as_string())
```

## Email Client MCP (Read/Send Emails)

**Package:** [mcp-email-server](https://github.com/ai-zerolab/mcp-email-server)

Read and send emails via IMAP/SMTP directly from Claude.

**Configured for:** `info@whyrating.com` on Stalwart

### Usage Examples
```
"Check my inbox"
"Read the latest email"
"Send an email to john@example.com with subject Hello"
"Search emails from support@"
"List email folders"
```

### Reconfigure
```bash
claude mcp remove email-client
claude mcp add email-client \
  -e MCP_EMAIL_SERVER_EMAIL_ADDRESS=info@whyrating.com \
  -e MCP_EMAIL_SERVER_PASSWORD=whyrating2026 \
  -e MCP_EMAIL_SERVER_IMAP_HOST=192.168.1.3 \
  -e MCP_EMAIL_SERVER_IMAP_PORT=143 \
  -e MCP_EMAIL_SERVER_SMTP_HOST=192.168.1.3 \
  -e MCP_EMAIL_SERVER_SMTP_PORT=587 \
  -e MCP_EMAIL_SERVER_SMTP_VERIFY_SSL=false \
  -e MCP_EMAIL_SERVER_ENABLE_ATTACHMENT_DOWNLOAD=true \
  --scope user \
  -- uvx mcp-email-server@latest stdio
```

## Adding Remote MCP Servers (HTTP Transport)

**Use `claude mcp add --transport http` for remote MCP endpoints** - this is the recommended method for services with native MCP support.

```bash
# Basic syntax
claude mcp add --transport http <name> <url> --scope user --header "<header>"

# Example: NocoDB MCP (globally available)
claude mcp add --transport http nocodb http://192.168.1.3:8084/mcp/ncnyir1cy6n9bf5p \
  --scope user \
  --header "xc-mcp-token: qjjAXRxuYzRtEn-cA4lbPFi5km_pojTX"
```

**Scope options:**
- `--scope user` - Available across all projects (stored in `~/.claude.json`)
- `--scope local` - Current project only (default)
- `--scope project` - Shared via `.mcp.json` (committed to repo)

**Why CLI over JSON config:**
- JSON config with `mcp-remote` often fails to load tools
- CLI `--transport http` handles HTTP endpoints natively
- No need for `--allow-http` flag or other workarounds

**Managing MCP servers:**
```bash
claude mcp list                    # List all configured servers
claude mcp get nocodb              # Get details for specific server
claude mcp remove nocodb           # Remove a server
/mcp                               # Check status in Claude Code
```

## Playwriter as Fallback

When SSH, API endpoints, or other MCPs can't accomplish a task (e.g., no API available, UI-only settings), use **Playwriter MCP** to automate browser interactions:

```javascript
// Navigate to service UI
await page.goto('http://192.168.1.3:8000');
// Get page state
console.log(await accessibilitySnapshot({ page }));
// Interact with elements
await page.locator('aria-ref=e5').click();
```

**Use cases:**
- Configuring services that lack APIs (Coolify UI settings, etc.)
- Creating OAuth apps, API keys through web interfaces
- Debugging issues by inspecting service dashboards
- Any task where clicking through a UI is the only option

## Remote Browser Container (NUC)

A dedicated browser container runs on the NUC for AI-controlled browsing without local resources:

**Access:**
- noVNC Web: `http://192.168.1.3:6081/vnc.html`
- Playwriter Relay: `ws://192.168.1.3:19988`
- Chrome DevTools: `http://192.168.1.3:9222`

**MCP connects remotely via:**
```json
{
  "playwriter-nuc-01": {
    "_id": "nuc-01",
    "_host": "192.168.1.3",
    "args": ["playwriter", "--host", "ws://192.168.1.3:19988", "--token", "nuc-browser-token"]
  }
}
```

**First-time setup:** Access noVNC, install Playwriter extension, click to activate (turns green).

**Container location:** `~/playwriter-browser/` on NUC (deployed via docker compose)