# DMARCReport MCP Server

[![npm version](https://img.shields.io/npm/v/@duocircle/dmarcreport-mcp.svg)](https://www.npmjs.com/package/@duocircle/dmarcreport-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

An MCP (Model Context Protocol) server that enables AI assistants to interact with the [DMARCReport](https://dmarcreport.com) API. Goes beyond data passthrough by providing DMARC-aware reasoning and actionable recommendations.

> **What is MCP?** [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that allows AI assistants to connect to external tools and data sources.

## Features

- **Full API Coverage** - Access all DMARCReport data (domains, aggregate reports, forensic reports, MTA-STS)
- **DMARC Reasoning** - Get intelligent analysis with grades, blockers, and recommendations
- **Policy Progression** - Check if domains are ready to advance from none → quarantine → reject
- **Configurable Profiles** - Novice, expert, and partner profiles for different user needs

## Quick Start

```bash
DMARCREPORT_API_KEY=your-key npx @duocircle/dmarcreport-mcp
```

> **Need an API key?** See the [API Token Setup Guide](https://support.dmarcreport.com/support/solutions/articles/5000873350-api-tokens) to generate one from your DMARCReport account.

## Installation

This MCP server works with any AI assistant that supports the Model Context Protocol.

### Claude Desktop

Add to your Claude Desktop configuration:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "dmarcreport": {
      "command": "npx",
      "args": ["@duocircle/dmarcreport-mcp"],
      "env": {
        "DMARCREPORT_API_KEY": "your-api-key",
        "DMARCREPORT_PROFILE": "novice"
      }
    }
  }
}
```

### Claude Code (CLI)

Add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "dmarcreport": {
      "command": "npx",
      "args": ["@duocircle/dmarcreport-mcp"],
      "env": {
        "DMARCREPORT_API_KEY": "your-api-key",
        "DMARCREPORT_PROFILE": "expert"
      }
    }
  }
}
```

Or use the CLI command:
```bash
claude mcp add dmarcreport -- npx @duocircle/dmarcreport-mcp
```

### Other MCP-Compatible AI Tools

This server follows the MCP standard and works with any compatible client. Configure your AI tool with:

- **Command:** `npx @duocircle/dmarcreport-mcp`
- **Environment:** `DMARCREPORT_API_KEY=your-api-key`

Refer to your AI tool's documentation for MCP server configuration.

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `DMARCREPORT_API_KEY` | Yes | - | Your DMARCReport API key |
| `DMARCREPORT_API_URL` | No | `https://api.dmarcreport.com` | API base URL |
| `DMARCREPORT_PROFILE` | No | `novice` | Analysis profile (novice/expert/partner) |
| `DMARCREPORT_CONFIG_FILE` | No | - | Path to JSON config file |

### Rate Limiting Configuration

The MCP server includes automatic rate limiting to prevent API throttling.

| Variable | Default | Description |
|----------|---------|-------------|
| `DMARCREPORT_MAX_CONCURRENT` | `5` | Maximum parallel API requests |
| `DMARCREPORT_MIN_TIME_MS` | `200` | Minimum milliseconds between requests |
| `DMARCREPORT_RESERVOIR` | `18` | Request budget per interval |
| `DMARCREPORT_RESERVOIR_INTERVAL_MS` | `20000` | Budget refresh interval (20 sec) |
| `DMARCREPORT_MAX_RETRIES` | `3` | Max retry attempts on 429/5xx errors |
| `DMARCREPORT_BASE_RETRY_DELAY_MS` | `1000` | Initial retry delay (1 sec) |
| `DMARCREPORT_MAX_RETRY_DELAY_MS` | `30000` | Maximum retry delay cap (30 sec) |

**Default behavior:**
- Max 5 API calls run in parallel
- 200ms minimum gap between requests
- 18 requests per 20-second window
- Automatic retry with exponential backoff on 429/5xx errors
- Respects `Retry-After` header when present

## Profiles

| Profile | Description | Best For |
|---------|-------------|----------|
| `novice` | Plain English explanations, simplified output | End users, non-technical stakeholders |
| `expert` | Technical details, DNS records, remediation diffs | IT administrators, email specialists |
| `partner` | MSP-focused, multi-tenant summaries, stricter thresholds | Managed service providers |

## Available Tools

### Account Tools
| Tool | Description |
|------|-------------|
| `list_accounts` | List all accessible accounts |
| `get_account` | Get account details |
| `get_email_sources` | List known email sources |

### Domain Tools
| Tool | Description |
|------|-------------|
| `list_domains` | List domains for an account |
| `get_domain` | Get domain details with DMARC/SPF/DKIM status |
| `get_hosted_services` | Get hosted DMARC and MTA-STS status |
| `verify_hosted_dmarc` | Verify hosted DMARC configuration |
| `generate_dmarc_record` | Generate DMARC DNS record |

### Report Tools
| Tool | Description |
|------|-------------|
| `get_aggregate_reports` | List DMARC aggregate reports |
| `get_aggregate_report` | Get detailed aggregate report |
| `get_aggregate_report_records` | Get individual report records |
| `get_aggregate_report_stats` | Get DMARC statistics |
| `get_forensic_reports` | List forensic (failure) reports |
| `get_forensic_report` | Get detailed forensic report |
| `get_mta_sts_reports` | List MTA-STS TLS reports |
| `get_mta_sts_report` | Get detailed MTA-STS report |

### Analysis Tools
| Tool | Description |
|------|-------------|
| `get_domain_summary` | Comprehensive domain overview with alignment stats |
| `get_top_sources` | Top email sources by volume |
| `get_alignment_failures` | SPF/DKIM failures ranked by volume |
| `get_mta_sts_status` | MTA-STS status and recent reports |

### Reasoning Tools
| Tool | Description |
|------|-------------|
| `analyze_domain_posture` | Security grade (A-F), blockers, recommendations |
| `policy_progression_check` | Check readiness for policy advancement |
| `compliance_summary` | Account-wide compliance scorecard |

## Example Prompts

Once configured, you can ask your AI assistant:

**Domain Analysis**
- "List all my DMARC domains"
- "What's the DMARC status of example.com?"
- "Analyze the security posture of my domain"

**Policy Progression**
- "Is example.com ready for p=quarantine?"
- "What's blocking my domain from moving to reject policy?"
- "Show me domains that are ready to advance their policy"

**Troubleshooting**
- "Which senders are failing DKIM alignment?"
- "Show me the top email sources for my domain"
- "What are the recent forensic reports for example.com?"

**Compliance**
- "Give me a compliance summary for my account"
- "Which domains need attention?"
- "What's my overall DMARC alignment rate?"

## Configuration File

Create a `config.json` for custom settings:

```json
{
  "profile": "expert",
  "thresholds": {
    "min_alignment_for_quarantine": 90,
    "min_alignment_for_reject": 98,
    "analysis_window_days": 30,
    "min_volume_for_recommendation": 100
  },
  "output": {
    "explain_technical_terms": false,
    "include_dns_records": true,
    "show_remediation_diffs": true
  }
}
```

Then set `DMARCREPORT_CONFIG_FILE=/path/to/config.json`.

## Support

- [DMARCReport](https://dmarcreport.com) - Email Authentication Made Simple
- [Help Center](https://support.dmarcreport.com)
- [API Token Setup Guide](https://support.dmarcreport.com/support/solutions/articles/5000873350-api-tokens)
- [GitHub Issues](https://github.com/duocircle/dmarcreport-mcp/issues)

## License

MIT