home / mcp / spamassassin mcp server

SpamAssassin MCP Server

Provides defensive email security analysis by integrating SpamAssassin via MCP, with safe, containerized operations.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "btafoya-spamassassin-mcp": {
      "url": "http://localhost:8081/mcp",
      "headers": {
        "UPDATE_RULES": "false",
        "MCP_TRANSPORT": "auto",
        "SA_MCP_HOST_PORT": "8081",
        "SA_MCP_LOG_LEVEL": "info",
        "SA_MCP_SERVER_BIND_ADDR": "0.0.0.0:8080",
        "SA_MCP_SPAMASSASSIN_HOST": "localhost",
        "SA_MCP_SPAMASSASSIN_PORT": "783",
        "SA_MCP_SPAMASSASSIN_THRESHOLD": "5.0",
        "SA_MCP_SECURITY_MAX_EMAIL_SIZE": "10485760"
      }
    }
  }
}

You set up a secure, containerized MCP server that analyzes email content with SpamAssassin. This server provides defensive email security analysis within a controlled environment, enabling you to scan messages, check sender reputations, test rules, and inspect configurations without sending emails or generating malicious content.

How to use

To use the SpamAssassin MCP Server, connect with an MCP client using SSE transport at the server URL. This enables you to scan emails, check sender reputations, and review current configuration. You can also run the local stdio transport to interact directly from the command line.

Key workflows you can perform include analyzing an email for spam probability and rule matches, verifying sender reputation against blacklists, and obtaining a snapshot of the current SpamAssassin configuration. All actions are defensive and do not perform email sending or content generation.

How to install

Prerequisites you need before installing are Docker and Docker Compose, plus access to an MCP client that supports the server.

Option A: Build and start with Docker Compose

# Clone or create the project directory
cd spamassassin-mcp

# Optional: Copy and customize configuration
cp .env.example .env
# Edit .env to customize ports and settings

# Build and start the containers
docker compose up -d

# Check health
docker compose logs spamassassin-mcp

Option B: Use a pre-built Docker image

# Pull the latest image from Docker Hub
docker pull your-dockerhub-username/spamassassin-mcp:latest

# Run the container
docker run -d \
  --name spamassassin-mcp \
  -p 8081:8080 \
  your-dockerhub-username/spamassassin-mcp:latest

Connect to the MCP server using SSE transport via this URL: http://localhost:8081/mcp. For direct interaction from the host, you can also run the local MCP server binary if provided by your setup.

Additional content

Configuration and basic usage details help you tailor the server to your environment. The server is designed for defensive analysis only, with safeguards to prevent email transmission and content generation. Security settings include rate limiting, input validation, and container isolation to reduce risk.

Health monitoring and troubleshooting steps let you verify the container health and SpamAssassin connectivity. Use the provided health check script or the standard Docker logging commands to diagnose issues.

Security and operational notes

Defensive posture ensures the MCP server only analyzes content and metadata. It does not send emails, relay messages, generate malicious content, or perform offensive security operations. All interactions are logged for auditability, and network boundaries keep operations isolated.

The server runs with non-root privileges, uses a read-only filesystem where possible, and enforces resource limits to prevent abuse. It is designed to handle input safely, sanitize content, and apply strict validation on all endpoints.

Troubleshooting

If you encounter a container restart loop, verify that the environment matches the expected transport mode. Port conflicts are resolved by adjusting SA_MCP_HOST_PORT in the .env file. If you see network subnet conflicts, consider modifying the docker-compose networks configuration. For health check failures, run the health-check script manually and review container logs for spamd activity.

Notes and examples

Common workflows include scanning an email, verifying sender reputation, and retrieving the current configuration. Use the provided command patterns to perform these tasks from your MCP client or local endpoint.

Available tools

scan_email

Analyze email content for spam probability and rule matches with optional verbose and Bayesian analysis.

check_reputation

Check sender reputation and domain/IP blacklists.

explain_score

Explain how a spam score was calculated with a detailed breakdown.

get_config

Retrieve current SpamAssassin configuration and status.

update_rules

Update SpamAssassin rule definitions (defensive updates only).

test_rules

Test custom rules against sample emails in a safe environment.