Tradecraft MCP

An OSINT (Open Source Intelligence) tradecraft toolkit exposed as an MCP 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

# Install dependencies
uv sync

# Run the server
uv run tradecraft-mcp

Claude Desktop

Add to your claude_desktop_config.json:

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

Claude Code

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

MCP Inspector

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.

# 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:

{
  "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

# 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:

# 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:

# 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

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.

Related MCP server: OSINT MCP Server

Tools

Domain / IP / DNS Recon (9 tools)

Email & Identity (6 tools)

Threat Intelligence (7 tools)

Web & Social Media (7 tools)

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:

cp .env.example .env

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

Development

# 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