# validin-mcp

MCP server for the [Validin](https://www.validin.com/) threat intelligence platform — exposes Validin's DNS, WHOIS, OSINT, certificate, crawl, and threat data as tools for AI agents via the [Model Context Protocol](https://modelcontextprotocol.io/).

## Features

**55+ tools** across every Validin API endpoint:

| Category | Tools | What you get |
|----------|-------|-------------|
| **Domains** | 16 | DNS history (A/AAAA/NS/MX/TXT/CNAME), subdomains, OSINT, reputation, certificates (CT), crawl history, WHOIS (historical + live), pivots, lookalikes |
| **IP Addresses** | 8 | Reverse DNS, OSINT, reputation, crawl history, pivots, live WHOIS |
| **CIDR Ranges** | 5 | DNS, OSINT, pivots, crawl, WHOIS across entire ranges |
| **Strings** | 6 | Pivot on server banners, JARM hashes, page titles, cert CNs, registrant emails/orgs |
| **Hashes** | 6 | Retrieve HTML/favicon/cert content by hash, crawl history, pivot on fingerprints |
| **Threats** | 6 | Named threat groups, malware families, IOCs, recent reports and indicators |
| **Projects** | 9 | List/manage projects, indicators, tags, notes, alerts, YARA rules and matches |
| **Bulk & Scans** | 4 | Bulk OSINT enrichment, on-demand live HTTP/S scans |
| **Advanced** | 2 | VQL advanced search, domain submissions |
| **Utilities** | 3 | Ping, usage stats |

## Quickstart

### Install

```bash
pip install validin-mcp
```

Or install from source:

```bash
git clone https://github.com/xelemental/validin-mcp.git
cd validin-mcp
pip install -e .
```

### Set your API key

Get your key from [Validin](https://app.validin.com/) → Profile → API Keys.

```bash
export VALIDIN_API_KEY="your-api-key-here"
```

### Run

```bash
# stdio transport (default — for Claude Desktop, Claude Code, etc.)
validin-mcp

# Or run as a module
python -m validin_mcp

# Streamable HTTP transport (for remote/shared deployment)
VALIDIN_MCP_TRANSPORT=streamable-http validin-mcp
```

## Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "validin": {
      "command": "validin-mcp",
      "env": {
        "VALIDIN_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add validin -- validin-mcp
```

Then set the env var `VALIDIN_API_KEY` in your shell.

### Using with uvx (no install)

```json
{
  "mcpServers": {
    "validin": {
      "command": "uvx",
      "args": ["validin-mcp"],
      "env": {
        "VALIDIN_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Tool Reference

### Domain Investigation

| Tool | Description |
|------|-------------|
| `domain_combined` | All outgoing connections — recommended starting point |
| `domain_dns_history` | Full historical DNS records (A, AAAA, NS) |
| `domain_dns_history_a` | Historical A records only |
| `domain_subdomains` | Subdomain enumeration |
| `domain_dns_extra` | SOA, MX, TXT, CNAME, CAA, SRV, HTTPS records |
| `domain_osint` | OSINT observations and threat references |
| `domain_reputation` | Quick reputation verdict |
| `domain_pivots` | Host-response pivots (headers, hashes, certs) |
| `domain_pivots_by_category` | Pivots filtered by category |
| `domain_certificates` | Certificate Transparency log data |
| `domain_crawl_history` | HTTP crawl snapshots over time |
| `domain_registration_history` | Normalized WHOIS/RDAP history |
| `domain_registration_live` | Live WHOIS/RDAP lookup |
| `domain_lookalike` | Typosquatting/impersonation detection |
| `lookalike_regex` | Regex-based lookalike hunting |

### IP & CIDR Investigation

| Tool | Description |
|------|-------------|
| `ip_combined` | All connections — recommended starting point |
| `ip_dns_history` | Historical A/AAAA records for this IP |
| `ip_dns_extra` | Extra DNS (HTTPS, SRV) for IP |
| `ip_osint` / `cidr_osint` | OSINT observations |
| `ip_reputation` | Quick reputation verdict |
| `ip_pivots` / `cidr_pivots` | Host-response pivots |
| `ip_crawl_history` / `cidr_crawl_history` | HTTP crawl data |
| `ip_registration_live` / `cidr_registration_live` | Live WHOIS |
| `cidr_dns_history` | DNS for entire CIDR range |

### String Pivoting

| Tool | Description |
|------|-------------|
| `string_dns_history` | Domains with this string in DNS responses |
| `string_dns_extra` | Extra DNS records containing this string |
| `string_registration_history` | WHOIS records containing this string |
| `string_registration_by_category` | WHOIS by field (registrant email, org, etc.) |
| `string_pivots` | Host-response pivots (JARM, server, title, cert CN) |
| `string_pivots_by_category` | Filtered by pivot category |

### Hash Operations

| Tool | Description |
|------|-------------|
| `hash_html_content` | Fetch HTML page by SHA1 |
| `hash_favicon_content` | Fetch favicon by MD5 |
| `hash_certificate_content` | Fetch certificate by SHA1 |
| `hash_crawl_history` | Crawl results for a hash |
| `hash_pivots` | Pivot on fingerprints |
| `hash_pivots_by_category` | Filter by hash category |

### Threat Intelligence

| Tool | Description |
|------|-------------|
| `threat_names` | List all tracked threats/groups/malware |
| `threat_summary` | Summary for a specific threat group |
| `threat_reports` | Published reports for a threat group |
| `threat_indicators` | IOCs for a threat group |
| `threat_reports_recent` | Latest published threat reports |
| `threat_indicators_recent` | Latest reported indicators |

### Projects & Collaboration

| Tool | Description |
|------|-------------|
| `project_list` | List all projects |
| `project_details` | Project metadata |
| `project_indicators` | Indicators in a project |
| `project_add_indicators` | Add indicators to a project |
| `project_delete_indicators` | Remove indicators |
| `project_add_tags` | Tag indicators |
| `project_add_note` | Annotate indicators |
| `project_alerts_latest` | Recent project alerts |
| `project_yara_rules` / `project_yara_matches` | YARA management |

### Bulk & Active Scanning

| Tool | Description |
|------|-------------|
| `bulk_osint` | Bulk OSINT verdicts for a list of indicators |
| `live_scan_start` | Start an on-demand HTTP/S scan |
| `live_scan_results` | Poll scan status/results |
| `live_scan_crawl_results` | Detailed crawl results from scan |

### Advanced & Utility

| Tool | Description |
|------|-------------|
| `advanced_query` | Validin Query Language (VQL) search |
| `submit_domains` | Submit domains for Validin scanning |
| `ping` | API connectivity test |
| `profile_usage` | Current API quota |
| `profile_usage_daily` | Daily usage breakdown |

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `VALIDIN_API_KEY` | Yes | Your Validin API key |
| `VALIDIN_MCP_TRANSPORT` | No | Transport mode: `stdio` (default) or `streamable-http` |

## Requirements

- Python ≥ 3.10
- A Validin account with API access ([Community](https://app.validin.com/) tier has limited API access)

## License

MIT