spamtitan-mcp
An MCP server that connects AI assistants (Claude, etc.) to SpamTitan email security for quarantine management, allowlist/blocklist administration, and filtering statistics.
Quarantine: list/filter the quarantine queue by sender, recipient, subject, or reason (paginated); fetch a single message by ID (renders as an interactive card in MCP Apps hosts); release messages to recipients; permanently delete messages (destructive, irreversible — confirmation required).
Lists: add, remove, or list sender allowlist entries (allowlisted senders bypass spam filtering).
Lists: add, remove, or list sender blocklist entries (blocklisted senders are rejected or quarantined; reversible).
Stats: view email flow statistics — received, blocked, quarantined, delivered — filterable by period (today through last 90 days) and domain.
Discovery/status:
spamtitan_navigatereturns tools by domain;spamtitan_statusshows credential status and available domains.Transports/auth: stdio or HTTP with S2S-signed requests; gateway mode takes per-request SpamTitan API key and base URL headers, env mode uses configured credentials.
Brandable UI: interactive message card customizable via
MCP_BRAND_*env vars orwindow.__BRAND__injection.
SpamTitan MCP Server
A Model Context Protocol (MCP) server for SpamTitan email security. Enables AI assistants to manage quarantine, maintain allowlists and blocklists, and view email filtering statistics.
This is a Model Context Protocol (MCP) server that connects Claude (or any MCP-compatible AI) to your SpamTitan environment.
Part of the MSP Claude Plugins ecosystem — a growing suite of AI integrations for the MSP stack. Built by MSPs, for MSPs.
Installation
npm install @wyre-ai/spamtitan-mcpRelated MCP server: knowbe4-mcp
Configuration
Copy .env.example and set the variables below.
Variable | Required | Description |
| For stdio and | SpamTitan API key |
| No | SpamTitan instance URL, including any path prefix (e.g. |
| No |
|
| No |
|
| Yes for HTTP | Service-to-service secret. The HTTP server logs an error and exits non-zero when this is empty or a known placeholder ( |
| No | Set to exactly |
| No | Bind address when a real |
| No | HTTP port. Defaults to |
/health and /healthz stay unauthenticated and do not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.
HTTP authentication
With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The check is verifyS2sHeader in src/s2s-verify.ts: the header value is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of the literal string t=<unix seconds> keyed with CONDUIT_S2S_SECRET (64 lowercase hex characters). The timestamp must be within 300 seconds of the server clock. A missing or invalid header is HTTP 401, before vendor credentials are read.
TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
-H "X-SpamTitan-API-Key: $SPAMTITAN_API_KEY" \
-H "X-SpamTitan-Base-URL: $SPAMTITAN_BASE_URL" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'In AUTH_MODE=gateway, /mcp also requires X-SpamTitan-API-Key. That header is the only API-key source for the request. X-SpamTitan-Base-URL is optional and, when present, selects the tenant instance. AUTH_MODE=env still requires the signed X-Gateway-S2S header, then uses SPAMTITAN_API_KEY and SPAMTITAN_BASE_URL from the environment.
Usage
Running with Claude Desktop
Add to your Claude Desktop claude_desktop_config.json:
{
"mcpServers": {
"spamtitan-mcp": {
"command": "npx",
"args": ["@wyre-ai/spamtitan-mcp"],
"env": {
"SPAMTITAN_API_KEY": "your-spamtitan-api-key"
}
}
}
}Running with Claude Code (CLI)
claude mcp add spamtitan-mcp \
-e SPAMTITAN_API_KEY=your-value \
-- npx -y @wyre-ai/spamtitan-mcpDocker
The image listens on 0.0.0.0 inside the container (MCP_HTTP_HOST) and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass a real S2S secret. In gateway mode, SpamTitan credentials arrive on each request as headers; the API key is not read from the environment.
docker build -t spamtitan-mcp .
docker run \
-e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
-p 127.0.0.1:8080:8080 \
spamtitan-mcpCompose refuses to start when CONDUIT_S2S_SECRET is unset or empty. The gateway service sets AUTH_MODE=gateway, does not inject SPAMTITAN_API_KEY or SPAMTITAN_BASE_URL, and publishes 127.0.0.1:8080:8080:
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose upSingle-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses SPAMTITAN_API_KEY and SPAMTITAN_BASE_URL. It is separate from the gateway Compose service above.
docker run \
-e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
-e AUTH_MODE=env \
-e SPAMTITAN_API_KEY=your-value \
-e SPAMTITAN_BASE_URL=https://mail.example.com/spamtitan/ \
-p 127.0.0.1:8080:8080 \
spamtitan-mcpLocal HTTP without a secret is development-only. It binds 127.0.0.1 and logs a warning. A non-loopback MCP_HTTP_HOST (including the image default 0.0.0.0) makes startup exit:
MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_ALLOW_INSECURE_DEV=1 npm startAvailable Domains
Lists
Manage allowlists and blocklists
Quarantine
Email quarantine review and management
Stats
Email filtering statistics and reports
Features
Interactive quarantined-message card (MCP Apps, SEP-1865) —
spamtitan_get_messagerenders as a read-only interactive card in MCP Apps hosts (Claude Desktop/web); plain-JSON behavior is unchanged in other hosts. The card is neutral by default, brandable viawindow.__BRAND__injection orMCP_BRAND_*env vars (MCP_BRAND_NAME,MCP_BRAND_LOGO_URL,MCP_BRAND_PRIMARY_COLOR,MCP_BRAND_ACCENT_COLOR,MCP_BRAND_BG,MCP_BRAND_TEXT) — no rebuild needed. Rebuild the card bundle withnpm run build:uiafter editingui/.
Development
# Clone the repository
git clone https://github.com/WYRE-AI/spamtitan-mcp.git
cd spamtitan-mcp
# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test
# HTTP refuses to start until CONDUIT_S2S_SECRET is a real secret
MCP_TRANSPORT=http CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm start
# Local HTTP only, without a service-to-service secret (binds 127.0.0.1)
MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_ALLOW_INSECURE_DEV=1 npm startContributing
Contributions are welcome! Please see CONTRIBUTING.md if present, or open an issue to discuss changes.
License
Licensed under the Apache License, Version 2.0. See LICENSE for details.
Available Tools
9 toolsspamtitan_delete_messageADestructive
⚠ DESTRUCTIVE — IRREVERSIBLE. Permanently delete a quarantined message by ID. This action cannot be undone and will remove the message from quarantine storage. Confirm with the user before invoking.
Inputs: message_id (required).
spamtitan_get_messageA
Get a single quarantined message by ID. Returns sender, recipient, subject, quarantine reason, spam score, and status. Renders as an interactive card in MCP Apps hosts.
Inputs: message_id (required).
spamtitan_get_queueA
List the email quarantine queue. Returns quarantined messages with sender, recipient, subject, and reason for quarantine.
Inputs: page, reason, sender, subject, +2 more.
spamtitan_get_statsA
Get email flow statistics from SpamTitan including messages received, blocked, quarantined, and delivered. Supports filtering by time period.
Inputs: domain, period.
spamtitan_manage_allowlistA
Add or remove sender allowlist entries in SpamTitan. Allowlisted senders always bypass spam filtering.
Inputs: action (required), note, sender.
spamtitan_manage_blocklistADestructiveIdempotent
⚠ HIGH-IMPACT. Add or remove sender blocklist entries in SpamTitan. Modifies email delivery policy and affects deliverability for users. Blocklisted senders are always rejected or quarantined. Reversible by removing entries. Confirm with the user before invoking.
Inputs: action (required), note, sender.
spamtitan_release_messageB
Release a quarantined message by ID, delivering it to the intended recipient.
Inputs: message_id (required).
spamtitan_statusB
Show credentials status and available domains
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct resource/action: status, discovery, queue listing, message retrieval, release, delete, allowlist management, blocklist management, and stats. The destructive and high-impact tools are clearly separated from safe read operations.
The spamtitan_ prefix creates a consistent namespace, and most tools follow verb_noun naming (get_queue, get_message, release_message, delete_message, manage_allowlist, get_stats). spamtitan_status and spamtitan_navigate are minor deviations from that pattern.
Nine tools is well-scoped for a SpamTitan server: quarantine lifecycle, list management, status, stats, and a discovery helper. Each tool earns its place without redundancy or bloat.
The quarantine workflow is fully covered with list, get, release, and delete, and allow/block list modifications plus stats are present. Minor gaps include no direct way to view current allowlist/blocklist entries and no search/filter for the queue, but these are workable.
Maintenance
Related MCP Connectors
Hosted MCP server for your Gmail, Outlook and IMAP mail, with mailboxes and scopes set per agent.
Remote MCP server: 19 domain-hygiene and email-auth tools (DNS, SPF, DMARC, DKIM, TLS).
MCP server for MailTempo's public free temporary email inboxes.
MCP server for GLPI: tickets, ITIL, assets, knowledge base. GLPI 10/11. Not affiliated with Teclib'.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for Checkpoint Harmony Email & Collaboration (Avanan). Enables AI assistants to manage email security, anti-phishing, anti-malware, and threat detection via the Avanan API.131Apache 2.0
- AlicenseBqualityBmaintenanceMCP server for KnowBe4 — security awareness training, phishing simulation, and user risk management API integration30Apache 2.0
- AlicenseNot gradedqualityBmaintenanceMCP server for ThreatLocker — zero-trust application allowlisting, approval requests, audit logs1Apache 2.0
- AlicenseBqualityBmaintenanceMCP server for Proofpoint Email Protection - email security, threat intelligence, TAP (Targeted Attack Protection), and email filtering API integration406Apache 2.0