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)

curl -s -u "admin:QfKYjCJdxu" "http://192.168.1.3:8081/api/principal" | jq .

Reconfigure MCP

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:

   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)

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

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

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.

# 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:

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:

// 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:

{
  "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)