Osint MCP Server

---

The Problem

OSINT collection is the first step of every penetration test, bug bounty, and threat assessment. The data you need is scattered across a dozen platforms — each with its own API, its own auth, its own rate limits, its own output format. Today you open Shodan in one tab, VirusTotal in another, run dig in a terminal, copy-paste from WHOIS, switch to crt.sh for certificates, and then spend 30 minutes manually correlating everything.

Traditional OSINT workflow:
  resolve DNS records            →  dig / nslookup CLI
  check WHOIS registration       →  whois CLI or web tool
  enumerate subdomains           →  crt.sh + SecurityTrails + VirusTotal (3 different UIs)
  scan for open ports/services   →  Shodan web interface
  check domain reputation        →  VirusTotal web interface
  map IP infrastructure          →  Censys + BGP lookups
  find archived pages            →  Wayback Machine web UI
  check email security           →  manual MX/SPF/DMARC lookups
  correlate everything           →  copy-paste into a spreadsheet
  ─────────────────────────────────
  Total: 45+ minutes per target, most of it switching contexts

osint-mcp-server gives your AI agent 37 tools across 12 data sources via the Model Context Protocol. The agent queries all sources in parallel, correlates data, identifies risks, and presents a unified intelligence picture — in a single conversation.

With osint-mcp-server:
  You: "Do a full recon on target.com"

  Agent: → DNS: 4 A records, 3 MX (Google Workspace), 2 NS
         → WHOIS: Registered 2019, expires 2025, GoDaddy
         → crt.sh: 47 unique subdomains from CT logs
         → HackerTarget: 23 hosts with IPs
         → Email: SPF soft-fail (~all), DMARC p=none, no DKIM
         → Shodan: 3 IPs, 12 open ports, Apache 2.4.49 (CVE-2021-41773)
         → VirusTotal: Clean reputation, 0 detections
         → "target.com has 47 subdomains, weak email security
            (SPF soft-fail, DMARC monitoring only), and one IP
            running Apache 2.4.49 with a known path traversal CVE.
            Priority: patch Apache, upgrade SPF to -all, set DMARC to p=reject."

---

How It's Different

Existing OSINT tools give you raw data one source at a time. osint-mcp-server gives your AI agent the ability to reason across all sources simultaneously.

---

Quick Start

Option 1: npx (no install)

npx osint-mcp-server

21 public OSINT tools work immediately. No API keys required.

Option 2: Clone

git clone https://github.com/badchars/osint-mcp-server.git
cd osint-mcp-server
bun install

Environment variables (optional)

# Premium OSINT sources — all optional
export SHODAN_API_KEY=your-key           # Enables 4 Shodan tools
export VT_API_KEY=your-key               # Enables 4 VirusTotal tools
export ST_API_KEY=your-key               # Enables 3 SecurityTrails tools
export CENSYS_API_ID=your-id             # Enables 3 Censys tools
export CENSYS_API_SECRET=your-secret     # Required with CENSYS_API_ID

All premium API keys are optional. Without them, you still get 21 tools covering DNS, WHOIS, crt.sh, GeoIP, BGP, Wayback Machine, HackerTarget, and Microsoft 365 tenant discovery.

Connect to your AI agent

# With npx
claude mcp add osint-mcp-server -- npx osint-mcp-server

# With local clone
claude mcp add osint-mcp-server -- bun run /path/to/osint-mcp-server/src/index.ts

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "osint": {
      "command": "npx",
      "args": ["-y", "osint-mcp-server"],
      "env": {
        "SHODAN_API_KEY": "optional",
        "VT_API_KEY": "optional",
        "ST_API_KEY": "optional",
        "CENSYS_API_ID": "optional",
        "CENSYS_API_SECRET": "optional"
      }
    }
  }
}

Same JSON config format. Point the command to npx osint-mcp-server or your local installation path.

Start querying

You: "What can you find about example.com?"

That's it. The agent handles DNS, WHOIS, subdomains, email security, and more automatically.

---

What The AI Can Do

Domain Reconnaissance

You: "Do a full recon on target.com"

Agent: → osint_domain_recon {domain: "target.com"}
       → DNS: A records point to 3 IPs (AWS us-east-1)
       → WHOIS: Registered 2018 via Namecheap, expires 2026
       → crt.sh: 62 subdomains discovered
       → HackerTarget: 31 hosts with resolved IPs
       → Email: SPF hard-fail, DMARC p=reject, DKIM found (selector1)
       → "target.com is well-configured for email security.
          62 subdomains found — notable: staging.target.com,
          admin-portal.target.com, api-v2.target.com.
          Infrastructure is on AWS (us-east-1)."

Attack Surface Mapping

You: "Map the attack surface for 203.0.113.50"

Agent: → shodan_host {ip: "203.0.113.50"}
       → geoip_lookup {ip: "203.0.113.50"}
       → bgp_ip {ip: "203.0.113.50"}
       → whois_ip {ip: "203.0.113.50"}
       → dns_reverse {ip: "203.0.113.50"}
       → "203.0.113.50 (Hetzner, DE, AS24940)
          Open ports: 22/SSH, 80/HTTP, 443/HTTPS, 8080/HTTP-Proxy
          Apache 2.4.51, OpenSSH 8.9, nginx reverse proxy on 8080
          Reverse DNS: web1.target.com
          3 known CVEs flagged by Shodan"

Subdomain Enumeration (Multi-Source)

You: "Find all subdomains of target.com using every source available"

Agent: → crtsh_search {domain: "target.com"}              → 62 subdomains
       → st_subdomains {domain: "target.com"}              → 84 subdomains
       → vt_subdomains {domain: "target.com"}              → 41 subdomains
       → hackertarget_hostsearch {domain: "target.com"}    → 31 hosts
       → dns_wildcard_check {domain: "target.com"}         → No wildcard
       → "127 unique subdomains after dedup across 4 sources.
          Notable findings: staging.target.com, dev-api.target.com,
          jenkins.target.com (CI/CD exposure risk),
          old-admin.target.com (potential legacy system)"

Email Security Audit

You: "Analyze the email security posture of target.com"

Agent: → dns_email_security {domain: "target.com"}
       → dns_spf_chain {domain: "target.com"}
       → m365_tenant {domain: "target.com"}
       → "Email Security: HIGH RISK
          SPF: ~all (soft fail — spoofable)
          DMARC: p=none (monitoring only — not enforcing)
          DKIM: Found for selector1 (2048-bit, good)
          SPF chain: 7 includes, 2 services (Google Workspace, SendGrid)
          M365: Not a Microsoft tenant
          Recommendations:
          1. Upgrade SPF from ~all to -all
          2. Change DMARC from p=none to p=quarantine, then p=reject
          3. Add rua= to DMARC for aggregate reporting"

Historical Intelligence

You: "What was target.com running 3 years ago?"

Agent: → wayback_urls {domain: "target.com", limit: 500}
       → st_dns_history {domain: "target.com", type: "a"}
       → wayback_snapshots {url: "https://target.com/robots.txt"}
       → "DNS history: target.com moved from 198.51.100.1 (DigitalOcean)
          to 203.0.113.50 (AWS) in 2023.
          Wayback found 342 unique URLs including:
          - /admin/ (removed in 2024, was accessible)
          - /api/v1/docs (Swagger UI, still cached)
          - /wp-content/ (was WordPress, migrated)
          Old robots.txt disallowed /internal/ and /debug/"

---

Tools Reference (37 tools)

Tool	Description
dns_lookup	Resolve A, AAAA, MX, TXT, NS, SOA, CNAME, SRV records
dns_reverse	Reverse DNS (PTR) lookup for an IP address
dns_email_security	SPF + DMARC + DKIM analysis with risk scoring and recommendations
dns_spf_chain	Recursive SPF include chain resolution with service detection
dns_srv_discover	SRV + CNAME service discovery (Autodiscover, LDAP, SIP, Kerberos, etc.)
dns_wildcard_check	Wildcard DNS detection via random subdomain probe

Tool	Description
whois_domain	RDAP domain lookup — registrar, dates, nameservers, contacts
whois_ip	RDAP IP lookup — network name, CIDR, country, entities

Tool	Description
crtsh_search	Search CT logs via crt.sh — subdomain discovery + certificate details

Tool	Description
shodan_host	IP details: open ports, services, banners, vulnerabilities, OS, ASN
shodan_search	Search Shodan query language (e.g. apache port:443 country:US)
shodan_dns_resolve	Bulk hostname-to-IP resolution via Shodan
shodan_exploits	Search public exploit database (PoC, Metasploit modules)

Tool	Description
vt_domain	Domain reputation, detection stats, categories, DNS records
vt_ip	IP reputation, detection stats, ASN, network
vt_subdomains	Subdomain enumeration via VirusTotal
vt_url	URL scan + malware/phishing analysis

Tool	Description
st_subdomains	Subdomain enumeration (returns FQDNs)
st_dns_history	Historical DNS records with first/last seen dates
st_whois	Enhanced WHOIS with registrant/admin/technical contacts

Tool	Description
censys_hosts	Host search — IPs, services, ports, location, ASN
censys_host_details	Single host full details with all services
censys_certificates	Certificate search by domain, fingerprint, issuer

Tool	Description
geoip_lookup	IP geolocation: country, city, ISP, ASN, proxy/hosting/VPN detection
geoip_batch	Batch IP geolocation (up to 100 IPs at once)

Tool	Description
bgp_asn	ASN details + all announced IPv4/IPv6 prefixes
bgp_ip	IP prefix/ASN routing lookup with RIR allocation
bgp_prefix	Prefix details + announcing ASNs

Tool	Description
wayback_urls	Archived URL discovery — find old endpoints, hidden paths, removed content
wayback_snapshots	Snapshot history with timestamps and direct archive links

Tool	Description
hackertarget_hostsearch	Host/subdomain discovery with resolved IPs
hackertarget_reverseip	Reverse IP lookup — find all domains on an IP
hackertarget_aslookup	ASN information lookup

Tool	Description
m365_tenant	Discover M365 tenant ID, region, and OpenID configuration
m365_userrealm	Detect auth type (Managed/Federated), federation brand, auth endpoints

Tool	Description
osint_list_sources	List all OSINT sources, API key status, and tool counts
osint_domain_recon	Quick recon combining all free sources (DNS + WHOIS + crt.sh + HackerTarget + email security)

---

GitHub Actions

Use any of the 37 tools directly in your CI/CD pipeline:

# .github/workflows/security.yml
name: OSINT Security Check
on:
  schedule:
    - cron: '0 8 * * 1'  # Weekly Monday 8am
  workflow_dispatch:

jobs:
  recon:
    runs-on: ubuntu-latest
    steps:
      - name: Domain reconnaissance
        uses: badchars/osint-mcp-server@v1
        id: recon
        with:
          tool: osint_domain_recon
          args: '{"domain": "example.com"}'

      - name: Email security audit
        uses: badchars/osint-mcp-server@v1
        with:
          tool: dns_email_security
          args: '{"domain": "example.com"}'

      - name: Subdomain enumeration
        uses: badchars/osint-mcp-server@v1
        with:
          tool: crtsh_search
          args: '{"domain": "example.com"}'

      - name: Shodan scan (optional)
        uses: badchars/osint-mcp-server@v1
        with:
          tool: shodan_host
          args: '{"ip": "203.0.113.50"}'
        env:
          SHODAN_API_KEY: ${{ secrets.SHODAN_API_KEY }}

The action output is available via steps.<id>.outputs.result for further processing.

CLI Usage

# List all available tools
npx osint-mcp-server --list

# Run any tool directly
npx osint-mcp-server --tool dns_lookup '{"domain":"example.com","type":"A"}'
npx osint-mcp-server --tool osint_domain_recon '{"domain":"example.com"}'
npx osint-mcp-server --tool dns_email_security '{"domain":"example.com"}' --format text

# Tools requiring API keys
SHODAN_API_KEY=your-key npx osint-mcp-server --tool shodan_host '{"ip":"1.1.1.1"}'

---

Data Sources (12)

Source	Auth	Rate Limit	What it provides
DNS	None	None	A, AAAA, MX, TXT, NS, SOA, CNAME, SRV, PTR records
RDAP	None	1 req/s	Domain & IP WHOIS data (registrar, dates, contacts, CIDR)
crt.sh	None	0.5 req/s	Certificate Transparency logs, subdomain discovery
ip-api.com	None	45 req/min	IP geolocation, ISP, ASN, proxy/VPN/hosting detection
BGPView	None	0.5 req/s	ASN details, announced prefixes, IP routing info
HackerTarget	None	2 req/s	Host search, reverse IP, ASN lookup (50/day free)
Wayback Machine	None	1 req/s	Archived URLs, snapshot history, historical content
Microsoft 365	None	None	Tenant discovery, federation detection, auth type
Shodan	SHODAN_API_KEY	1 req/s	Internet-wide port/service/banner scanning
VirusTotal	VT_API_KEY	4 req/min	Domain/IP/URL reputation, malware detection
SecurityTrails	ST_API_KEY	1 req/s	DNS history, subdomain enumeration, enhanced WHOIS
Censys	CENSYS_API_ID	1 req/s	Host search, certificate transparency, service discovery

---

Design decisions:

• 12 providers, 1 server — Every OSINT source is an independent module. The agent picks which tools to use based on the query.
• 21 free tools — DNS, WHOIS, crt.sh, BGP, GeoIP, Wayback, HackerTarget, and M365 work without any API keys. Premium sources are additive.
• Parallel queries — osint_domain_recon calls 8 sources via Promise.allSettled. If one source times out, the rest still return data.
• Per-provider rate limiters — Each data source has its own RateLimiter instance calibrated to that API's limits. No shared bottleneck.
• TTL caching — crt.sh (15min), BGP (30min), Shodan (5min), VirusTotal (10min) results are cached to avoid redundant API calls during multi-tool workflows.
• Graceful degradation — Missing API keys don't crash the server. Tools return descriptive error messages: "Set SHODAN_API_KEY to enable Shodan tools."
• SPF chain analysis — Recursive include resolution with loop detection, service identification (Google Workspace, Microsoft 365, SendGrid, etc.), and RFC 7208 lookup limit checking.
• 2 dependencies — @modelcontextprotocol/sdk and zod. All HTTP via native fetch. All DNS via node:dns/promises.

---

Limitations

• Free-tier rate limits apply: HackerTarget (50/day), ip-api.com (45/min), VirusTotal community (4/min)
• crt.sh can be slow for large domains (30s timeout applied)
• ip-api.com requires HTTP (not HTTPS) for free tier
• Wayback Machine CDX API can timeout for very popular domains
• WHOIS via RDAP may not cover all TLDs (some registrars don't support RDAP yet)
• macOS / Linux tested (Windows not tested)

---

Part of the MCP Security Suite

Project	Domain	Tools
hackbrowser-mcp	Browser-based security testing	39 tools, Firefox, injection testing
cloud-audit-mcp	Cloud security (AWS/Azure/GCP)	38 tools, 60+ checks
github-security-mcp	GitHub security posture	39 tools, 45 checks
cve-mcp	Vulnerability intelligence	23 tools, 5 sources
osint-mcp-server	OSINT & reconnaissance	37 tools, 12 sources

---