# Tradecraft MCP

An OSINT (Open Source Intelligence) tradecraft toolkit exposed as an [MCP](https://modelcontextprotocol.io/) server. Provides 31 tools for domain reconnaissance, email/identity research, threat intelligence, and web/social media analysis — plus 12 prompt templates that guide structured investigation workflows.

17 tools work out of the box with no configuration. The remaining 14 unlock with optional API keys and the server gracefully tells you how to set them up when they're missing.

## Quick Start

```bash
# Install dependencies
uv sync

# Run the server
uv run tradecraft-mcp
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tradecraft-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/tradecraft-mcp", "tradecraft-mcp"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add tradecraft-mcp -- uv run --directory /path/to/tradecraft-mcp tradecraft-mcp
```

### MCP Inspector

```bash
uv run mcp dev src/tradecraft_mcp/server.py
```

### Remote Access (SSE / Streamable HTTP)

The server supports three transports: `stdio` (default), `sse`, and `streamable-http`. Use the HTTP-based transports to run the server on a machine and connect to it remotely.

```bash
# Start with SSE transport on default port 8000
uv run tradecraft-mcp --transport sse

# Start with streamable-http on a custom port
uv run tradecraft-mcp --transport streamable-http --port 9000

# Bind to a specific interface
uv run tradecraft-mcp --transport sse --host 127.0.0.1 --port 8080
```

Then configure your MCP client to connect to the remote URL:

```json
{
  "mcpServers": {
    "tradecraft-mcp": {
      "url": "http://<host>:8000/sse"
    }
  }
}
```

For `streamable-http`, the endpoint is `http://<host>:<port>/mcp`.

Run `uv run tradecraft-mcp --help` to see all options.

### Authentication

HTTP transports are open by default. Three authentication modes are supported: static bearer token, Google ID token verification, and full Google OAuth flow.

#### Static Bearer Token

```bash
# Via CLI flag
uv run tradecraft-mcp --transport sse --auth-token my-secret

# Via environment variable
MCP_AUTH_TOKEN=my-secret uv run tradecraft-mcp --transport streamable-http
```

Clients must then include `Authorization: Bearer my-secret` in every request. Requests without a valid token receive a 401 response.

#### Google ID Token Verification

Verify Google-issued JWT ID tokens without running a full OAuth flow. Requires only the Google OAuth2 client ID:

```bash
# Via CLI flags
uv run tradecraft-mcp --transport sse --google-client-id YOUR_CLIENT_ID

# Restrict to specific emails or domains
uv run tradecraft-mcp --transport sse \
  --google-client-id YOUR_CLIENT_ID \
  --google-allowed-emails alice@example.com,bob@example.com

uv run tradecraft-mcp --transport sse \
  --google-client-id YOUR_CLIENT_ID \
  --google-allowed-domains example.com,mycompany.com

# Via environment variables
MCP_GOOGLE_CLIENT_ID=YOUR_CLIENT_ID uv run tradecraft-mcp --transport sse
```

#### Full Google OAuth Flow

For a complete OAuth2 authorization code flow (consent screen, token exchange, refresh tokens), provide both the client ID and client secret:

```bash
# Via CLI flags
uv run tradecraft-mcp --transport sse \
  --google-client-id YOUR_CLIENT_ID \
  --google-client-secret YOUR_CLIENT_SECRET

# With email/domain restrictions
uv run tradecraft-mcp --transport sse \
  --google-client-id YOUR_CLIENT_ID \
  --google-client-secret YOUR_CLIENT_SECRET \
  --google-allowed-domains mycompany.com

# Via environment variables
MCP_GOOGLE_CLIENT_ID=YOUR_CLIENT_ID \
MCP_GOOGLE_CLIENT_SECRET=YOUR_CLIENT_SECRET \
  uv run tradecraft-mcp --transport sse
```

The server exposes `/oauth/google/callback` as the redirect URI — configure this in your Google Cloud Console OAuth credentials.

#### Auth Options Reference

| Option | Env Var | Description |
|---|---|---|
| `--auth-token` | `MCP_AUTH_TOKEN` | Static bearer token (enables simple auth when set) |
| `--google-client-id` | `MCP_GOOGLE_CLIENT_ID` | Google OAuth2 client ID (enables Google auth) |
| `--google-client-secret` | `MCP_GOOGLE_CLIENT_SECRET` | Google OAuth2 client secret (enables full OAuth flow) |
| `--google-allowed-emails` | `MCP_GOOGLE_ALLOWED_EMAILS` | Comma-separated allowed email addresses |
| `--google-allowed-domains` | `MCP_GOOGLE_ALLOWED_DOMAINS` | Comma-separated allowed email domains |
| `--issuer-url` | `MCP_AUTH_ISSUER_URL` | OAuth issuer URL (default: `http://localhost:<port>`) |
| `--required-scopes` | `MCP_AUTH_SCOPES` | Comma-separated required scopes |

CLI flags take precedence over environment variables. Auth is ignored for stdio transport. When both Google auth and a static token are configured, Google auth takes precedence.

## Tools

### Domain / IP / DNS Recon (9 tools)

| Tool | Description | API Key |
|---|---|---|
| `whois_lookup` | WHOIS for domain or IP — registrar, dates, nameservers | None |
| `dns_enumerate` | Query A, AAAA, MX, NS, TXT, CNAME, SOA records | None |
| `reverse_dns` | Reverse DNS on an IP to find hostnames | None |
| `cert_transparency_search` | Search crt.sh for certificates and subdomains | None |
| `subdomain_discover` | Subdomains via CT logs + optional brute-force + SecurityTrails | `SECURITYTRAILS_API_KEY` (optional) |
| `ip_geolocation` | Geo data — country, city, ISP, ASN | None |
| `shodan_host_lookup` | Shodan host info — ports, services, vulns, geo | `SHODAN_API_KEY` |
| `shodan_domain_search` | Shodan hosts for a domain | `SHODAN_API_KEY` |
| `censys_host_lookup` | Censys host — services, TLS, ASN | `CENSYS_API_ID` + `CENSYS_API_SECRET` |

### Email & Identity (6 tools)

| Tool | Description | API Key |
|---|---|---|
| `email_validate` | Format check + MX record verification | None |
| `email_domain_info` | MX, SPF, DKIM, DMARC analysis + mail provider detection | None |
| `gravatar_lookup` | Gravatar profile from email hash | None |
| `username_enumerate` | Check username across major platforms via HTTP probing | None |
| `hibp_breach_check` | Have I Been Pwned breach lookup | `HIBP_API_KEY` |
| `hibp_paste_check` | Have I Been Pwned paste index lookup | `HIBP_API_KEY` |

### Threat Intelligence (7 tools)

| Tool | Description | API Key |
|---|---|---|
| `threat_feed_check` | Check against Abuse.ch URLhaus, Feodo Tracker, SSL Blacklist | None |
| `virustotal_file_report` | VirusTotal analysis for a file hash | `VIRUSTOTAL_API_KEY` |
| `virustotal_url_scan` | VirusTotal scan/report for a URL | `VIRUSTOTAL_API_KEY` |
| `virustotal_domain_report` | VirusTotal domain reputation + DNS + detections | `VIRUSTOTAL_API_KEY` |
| `virustotal_ip_report` | VirusTotal IP reputation + associated URLs/files | `VIRUSTOTAL_API_KEY` |
| `abuseipdb_check` | AbuseIPDB reports, confidence, ISP | `ABUSEIPDB_API_KEY` |
| `ioc_enrich` | Auto-detect IOC type, query all relevant tools, consolidated report | Uses underlying keys |

### Web & Social Media (7 tools)

| Tool | Description | API Key |
|---|---|---|
| `web_fetch` | Fetch page as clean text + metadata, respects robots.txt | None |
| `web_headers_analyze` | Security header analysis — CSP, HSTS, X-Frame, cookies | None |
| `metadata_extract` | OpenGraph, Twitter Card, linked resources, tech fingerprint | None |
| `google_dork_generate` | Generate Google dork queries for a target + goal | None |
| `wayback_lookup` | Wayback Machine archived snapshots | None |
| `social_media_profile` | Extract public profile data from a social media URL | None |
| `website_technology_detect` | CMS, framework, CDN, analytics detection | None |

## Prompt Templates

Prompt templates guide structured investigation workflows. Select one to get a step-by-step methodology that calls the right tools in the right order.

### Domain Investigation
- **`domain_full_recon`** — Multi-phase domain recon (WHOIS, DNS, subdomains, services, web, history)
- **`infrastructure_mapping`** — Map an org's internet-facing infrastructure from a domain
- **`domain_threat_assessment`** — Assess domain threat posture with reputation + DNS + certs

### Person / Identity Investigation
- **`email_investigation`** — Start from email: validate, breaches, domain, gravatar, username search
- **`username_investigation`** — Start from username: enumerate platforms, find patterns, build profile
- **`person_osint`** — Full person investigation using all available identifiers

### Threat Assessment
- **`ioc_investigation`** — Investigate a suspicious IOC with enrichment + threat feeds
- **`malware_hash_analysis`** — Analyze malware hash: VT report + detection ratio + behavior
- **`suspicious_url_analysis`** — Analyze suspicious URL: reputation, WHOIS, cert, phishing checklist
- **`ip_threat_profile`** — Build IP threat profile: geo + Shodan + AbuseIPDB + VT + reverse DNS

### General OSINT
- **`osint_methodology`** — General OSINT methodology framework (plan, collect, process, analyze, report)
- **`attack_surface_discovery`** — Discover org attack surface: domains, services, creds, documents, tech

## API Keys

All keys are optional. Copy `.env.example` to `.env` and fill in the ones you have:

```bash
cp .env.example .env
```

| Variable | Service | How to Get |
|---|---|---|
| `SHODAN_API_KEY` | [Shodan](https://shodan.io) | [Register](https://account.shodan.io/register) (free tier available) |
| `CENSYS_API_ID` | [Censys](https://censys.io) | [API page](https://search.censys.io/account/api) |
| `CENSYS_API_SECRET` | [Censys](https://censys.io) | [API page](https://search.censys.io/account/api) |
| `VIRUSTOTAL_API_KEY` | [VirusTotal](https://virustotal.com) | [Sign up](https://www.virustotal.com/gui/join-us) (free tier available) |
| `HIBP_API_KEY` | [Have I Been Pwned](https://haveibeenpwned.com) | [Purchase key](https://haveibeenpwned.com/API/Key) |
| `ABUSEIPDB_API_KEY` | [AbuseIPDB](https://abuseipdb.com) | [Register](https://www.abuseipdb.com/register) (free tier available) |
| `SECURITYTRAILS_API_KEY` | [SecurityTrails](https://securitytrails.com) | [Sign up](https://securitytrails.com/corp/signup) (free tier available) |

When a tool requiring a missing key is called, it returns a clear error message with the setup URL — no cryptic failures.

## Development

```bash
# Install with dev dependencies
uv sync --group dev

# Run tests
uv run pytest tests/ -v

# Run a single test file
uv run pytest tests/test_domain_recon.py -v
```

## Project Structure

```
tradecraft-mcp/
├── pyproject.toml
├── src/
│   └── tradecraft_mcp/
│       ├── __init__.py               # Entry point, version
│       ├── __main__.py               # python -m tradecraft_mcp
│       ├── auth.py                   # Token verification (static + Google)
│       ├── oauth_provider.py         # Google OAuth authorization server provider
│       ├── server.py                 # FastMCP instance, lifespan, registration
│       ├── config.py                 # API key loading from env vars
│       ├── tools/
│       │   ├── __init__.py           # register_all_tools(mcp)
│       │   ├── domain_recon.py       # 9 tools
│       │   ├── email_identity.py     # 6 tools
│       │   ├── threat_intel.py       # 7 tools
│       │   └── web_social.py         # 7 tools
│       └── prompts/
│           ├── __init__.py           # register_all_prompts(mcp)
│           ├── domain_investigation.py
│           ├── person_investigation.py
│           ├── threat_assessment.py
│           └── general_osint.py
└── tests/
    ├── conftest.py
    ├── test_domain_recon.py
    ├── test_email_identity.py
    ├── test_threat_intel.py
    └── test_web_social.py
```

## Architecture

- **Authentication:** Optional auth for HTTP transports — static bearer token, Google ID token verification, or full Google OAuth2 flow (uses MCP SDK's `TokenVerifier` protocol and `OAuthAuthorizationServerProvider`)
- **Transport:** stdio (default), SSE, or streamable-http — selectable via `--transport`
- **HTTP session:** Single `aiohttp.ClientSession` shared across all tools via FastMCP lifespan
- **Output format:** Markdown strings optimized for LLM consumption
- **Error handling:** Missing API keys raise `ValueError` (surfaced by the MCP SDK as tool errors); network errors are caught and returned as descriptive strings
- **Logging:** All logging to stderr via Python `logging` — never stdout (MCP stdio transport requirement)

## License

MIT