osint-mcp-server

English | 简体中文 | 繁體中文 | 한국어 | Deutsch | Español | Français | Italiano | Dansk | 日本語 | Polski | Русский | Bosanski | العربية | Norsk | Português (Brasil) | ไทย | Türkçe | Українська | বাংলা | Ελληνικά | Tiếng Việt | हिन्दी

OSINT & reconnaissance intelligence for AI agents.

Shodan, VirusTotal, Censys, SecurityTrails, DNS, WHOIS, BGP, Wayback Machine — unified into a single MCP server.
Your AI agent gets full-spectrum OSINT on demand, not 12 browser tabs and manual correlation.

The Problem • How It's Different • Quick Start • What The AI Can Do • Tools (37) • Data Sources • Architecture • Changelog • Contributing

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

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

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)

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)

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

For authorized security testing and assessment only.
Always ensure you have proper authorization before performing reconnaissance on any target.

MIT License • Built with Bun + TypeScript