npm package: @leviai/netrecon-mcp
Description: Network reconnaissance MCP server — DNS, WHOIS, port scanning, subdomain enumeration, TLS inspection, HTTP security headers, IP geolocation, and Shodan InternetDB. Zero API keys required.
Author: Levi Labs
Latest version: 1.0.0

<p align="center">
  <h1 align="center">🔍 NetRecon MCP</h1>
  <p align="center">
    Network reconnaissance toolkit for AI assistants via the Model Context Protocol
    <br />
    <strong>10 tools · Zero API keys · Pure Node.js</strong>
  </p>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@leviai/netrecon-mcp"><img src="https://img.shields.io/npm/v/@leviai/netrecon-mcp.svg" alt="npm version"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-brightgreen.svg" alt="MCP Compatible"></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-green.svg" alt="Node.js >= 18"></a>
</p>

---

A comprehensive network reconnaissance MCP server that gives AI assistants the ability to perform DNS lookups, WHOIS queries, port scanning, subdomain enumeration, TLS certificate inspection, HTTP security header analysis, IP geolocation, and Shodan intelligence — all without any API keys.

## ⚡ Quick Start

```bash
npx @leviai/netrecon-mcp
```

That's it. No installation, no configuration, no API keys.

## 🛠️ Tools

| Tool | Description | Data Source |
|------|-------------|-------------|
| `dns_lookup` | Query DNS records (A, AAAA, MX, TXT, NS, SOA, CNAME, SRV, CAA) | Cloudflare + Google DNS |
| `whois_lookup` | WHOIS/RDAP registration data for domains and IPs | RDAP (rdap.org) |
| `reverse_dns` | Reverse DNS lookup — find hostnames for an IP | System DNS |
| `tls_certificate` | Inspect TLS/SSL certificates, SANs, validity, fingerprints | Direct TLS connection |
| `port_scan` | TCP connect scan on specified or common ports | Direct TCP connection |
| `subdomain_enum` | Discover subdomains via Certificate Transparency logs | crt.sh |
| `http_headers` | Fetch HTTP headers + security header analysis | Direct HTTP request |
| `ip_geolocation` | IP location, ISP, ASN, proxy/VPN/hosting detection | ip-api.com (free) |
| `shodan_internetdb` | Quick IP intel — open ports, CVEs, hostnames, CPEs | Shodan InternetDB (free) |
| `full_recon` | All-in-one comprehensive domain reconnaissance | All of the above |

## 📦 Installation

### Option 1: npx (no install)

```bash
npx @leviai/netrecon-mcp
```

### Option 2: Global install

```bash
npm install -g @leviai/netrecon-mcp
netrecon-mcp
```

### Option 3: Clone and build

```bash
git clone https://github.com/levi-labs/netrecon-mcp.git
cd netrecon-mcp
npm install
npm run build
node build/index.js
```

## 🔌 Client Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "netrecon": {
      "command": "npx",
      "args": ["-y", "@leviai/netrecon-mcp"]
    }
  }
}
```

<details>
<summary>📁 Config file locations</summary>

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

</details>

### Cursor

Add to Cursor Settings → MCP Servers:

```json
{
  "mcpServers": {
    "netrecon": {
      "command": "npx",
      "args": ["-y", "@leviai/netrecon-mcp"]
    }
  }
}
```

### Claude Code (CLI)

```bash
claude mcp add netrecon -- npx -y @leviai/netrecon-mcp
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "netrecon": {
      "command": "npx",
      "args": ["-y", "@leviai/netrecon-mcp"]
    }
  }
}
```

### OpenClaw

```bash
mcporter add netrecon --command "npx -y @leviai/netrecon-mcp"
```

## 💬 Example Prompts

Once connected, ask your AI assistant:

> "What DNS records does example.com have?"

> "Who owns the IP address 8.8.8.8?"

> "Scan ports on 203.0.113.1"

> "Find all subdomains of tesla.com"

> "Check the TLS certificate for github.com — is it expiring soon?"

> "Analyze the security headers of https://example.com"

> "Do a full security recon on cloudflare.com"

> "Is 1.2.3.4 a known proxy or VPN?"

> "What vulnerabilities are known for 203.0.113.50?"

## 📋 Example Output

### `dns_lookup` for github.com

```
DNS Records for github.com:

  A Records:
    140.82.121.3

  AAAA Records:
    2606:50c0:8000::64

  MX Records:
    1 aspmx.l.google.com
    5 alt1.aspmx.l.google.com
    10 alt3.aspmx.l.google.com

  NS Records:
    dns1.p08.nsone.net
    dns2.p08.nsone.net
    dns3.p08.nsone.net
    dns4.p08.nsone.net

  TXT Records:
    v=spf1 ip4:192.30.252.0/22 include:_netblocks...
```

### `port_scan` for a web server

```
Port scan for example.com:
  Open ports (4):
    22/tcp  open  SSH
    80/tcp  open  HTTP
    443/tcp open  HTTPS
    8080/tcp open  HTTP-Alt
```

### `http_headers` security analysis

```
HTTP Headers for https://example.com:
  Status: 200 OK
  Headers:
    content-type: text/html; charset=UTF-8
    strict-transport-security: max-age=31536000
    x-content-type-options: nosniff
    ...

  Security Analysis:
    ⚠ Missing: Content-Security-Policy (CSP)
    ⚠ Missing: Permissions-Policy
    ⚠ Info leak: Server header exposes "nginx/1.24.0"
```

## 🏗️ Architecture

```
┌──────────────┐     stdio/JSON-RPC     ┌──────────────────┐
│  MCP Client  │◄──────────────────────►│  NetRecon MCP    │
│  (Claude,    │                        │  Server          │
│   Cursor,    │                        │                  │
│   etc.)      │                        └───────┬──────────┘
└──────────────┘                                │
                           ┌────────────────────┼────────────────────┐
                           │                    │                    │
                    ┌──────▼──────┐     ┌──────▼──────┐     ┌──────▼──────┐
                    │  DNS        │     │  RDAP/WHOIS  │     │  crt.sh     │
                    │  (1.1.1.1)  │     │  (rdap.org)  │     │  (CT logs)  │
                    └─────────────┘     └──────────────┘     └─────────────┘
                           │                    │                    │
                    ┌──────▼──────┐     ┌──────▼──────┐     ┌──────▼──────┐
                    │  ip-api.com │     │  Shodan      │     │  Direct     │
                    │  (GeoIP)    │     │  InternetDB  │     │  TCP/TLS    │
                    └─────────────┘     └──────────────┘     └─────────────┘
```

## 🔑 No API Keys Required

Every data source is free and requires zero authentication:

| Source | Purpose | Rate Limit |
|--------|---------|------------|
| Cloudflare DNS (1.1.1.1) | DNS resolution | Unlimited |
| Google DNS (8.8.8.8) | DNS fallback | Unlimited |
| rdap.org | WHOIS/RDAP lookups | Fair use |
| crt.sh | Certificate Transparency logs | Fair use |
| ip-api.com | IP geolocation | 45 req/min |
| Shodan InternetDB | IP intelligence | Unlimited |
| Direct TCP/TLS | Port scan & TLS inspection | N/A |

## ⚖️ Security & Ethics

This tool is designed for **legitimate security assessment** of systems you own or have authorization to test. Port scanning and reconnaissance of systems without permission may violate laws in your jurisdiction. Use responsibly.

## 🤝 Contributing

Contributions welcome! Please open an issue first to discuss what you'd like to change.

```bash
git clone https://github.com/levi-labs/netrecon-mcp.git
cd netrecon-mcp
npm install
npm run dev
```

## 📄 License

[MIT](LICENSE) © Levi Labs