{
  "markdown": "# recon-mcp\n\n**English** | [繁體中文](./README.zh-TW.md)\n\n[![CI](https://github.com/nan786521/recon-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/nan786521/recon-mcp/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/recon-kit-mcp)](https://pypi.org/project/recon-kit-mcp/)\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)\n\nAn [MCP](https://modelcontextprotocol.io) server that gives AI coding agents —\n**Claude Code, Codex, Cline, and any MCP client** — safe, structured network and\nsecurity **reconnaissance** tools.\n\nMost MCP servers wrap CRUD APIs. `recon-mcp` instead exposes the kind of\nread-only recon an engineer reaches for when investigating an asset, and returns\nclean JSON — with a graded verdict — so the agent can reason over results\ninstead of parsing console output.\n\n> ⚠️ **Authorized use only.** These tools are for security testing of assets you\n> own or have explicit written permission to assess, for CTF practice, and for\n> education. Do not point them at third-party infrastructure without\n> authorization. You are responsible for how you use this software.\n\n## Tools\n\n| Tool | What it does |\n|------|--------------|\n| `recon_report` | **Start here.** One call → DNS, TLS, and HTTP headers checked together, with an overall grade |\n| `dns_recon` | DNS + WHOIS + email security (SPF/DMARC/DKIM), graded |\n| `subdomain_enum` | Discover subdomains via DNS brute-force and/or Certificate Transparency logs |\n| `subdomain_takeover` | Check subdomains for a dangling-CNAME takeover risk against known services |\n| `tls_check` | Certificate, protocols, ciphers, and known TLS vulnerabilities, graded |\n| `http_headers_audit` | HTTP security headers (CSP, HSTS, X-Frame-Options, …), graded |\n| `cookie_audit` | Redirect chain + cookie flags (Secure / HttpOnly / SameSite), graded |\n| `cors_check` | CORS policy probe — flags arbitrary-Origin reflection and wildcard misuse |\n| `tech_detect` | Fingerprint the web stack (server, CDN/WAF, language, framework, CMS, JS) from one GET |\n| `http_methods_audit` | Report which HTTP methods a server allows and grade the risk (TRACE/PUT/DELETE) |\n| `well_known_audit` | Fetches & parses `security.txt` (RFC 9116) and `robots.txt` |\n| `ip_info` | Resolves the host and enriches its IP via RDAP (owner, country, CIDR, abuse) |\n| `port_scan` | TCP port scan of one host (≤1024 ports/call), open ports + services |\n\n## Example\n\nJust ask your agent: *\"run a security recon report on example.com.\"* It calls\n`recon_report` once and gets a graded overview it can act on:\n\n```json\n{\n  \"domain\": \"example.com\",\n  \"overall_grade\": \"F\",\n  \"summary\": \"Overall posture F: email A, TLS B, headers F; 13 actionable issue(s).\",\n  \"components\": {\n    \"email\":   { \"grade\": \"A\", \"issues\": [] },\n    \"tls\":     { \"grade\": \"B\", \"issues\": [] },\n    \"headers\": { \"grade\": \"F\", \"issues\": [\n      { \"severity\": \"high\", \"label\": \"Missing Content-Security-Policy\", \"detail\": \"CSP not set; cannot restrict resource load sources\" }\n    ] }\n  }\n}\n```\n\nNeed more detail on one area? The agent can call `dns_recon`, `subdomain_enum`,\n`subdomain_takeover`, `tls_check`, `http_headers_audit`, `cookie_audit`,\n`cors_check`, `tech_detect`, `http_methods_audit`, `well_known_audit`,\n`ip_info`, or `port_scan` directly.\n\n## Install\n\nRequires Python ≥ 3.10. Runs on Linux, macOS, and Windows (tested in CI).\n\n**Recommended — no clone, via [uv](https://docs.astral.sh/uv/):**\n\n```bash\nuvx recon-kit-mcp\n```\n\n**Or from source (for development):**\n\n```bash\ngit clone https://github.com/nan786521/recon-mcp\ncd recon-mcp\npython -m venv .venv\n# Windows\n.venv\\Scripts\\activate\n# macOS / Linux\nsource .venv/bin/activate\npip install -e .\n```\n\n## Use with Claude Code\n\nAdd the server (stdio transport). With `uvx` you don't need an absolute path:\n\n```bash\nclaude mcp add recon -- uvx recon-kit-mcp\n```\n\nOr add it manually to any MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"recon\": {\n      \"command\": \"uvx\",\n      \"args\": [\"recon-kit-mcp\"]\n    }\n  }\n}\n```\n\n(From a source checkout, point the command at `/absolute/path/to/.venv/bin/recon-kit-mcp` instead.)\n\nThen just ask: *\"run a security recon report on example.com\"* — or target one\narea, e.g. *\"check the email security of example.com.\"*\n\nThe server also ships a **`security_recon` prompt**: pick it from your client's\nprompt menu and pass a domain for a guided, severity-sorted audit.\n\n## Tool reference\n\n### `recon_report(domain, timeout?) -> dict`\n\nRuns DNS/email, TLS, HTTP-header, web-stack (`tech_detect`), and apex\nsubdomain-takeover checks together and returns `overall_grade` (as weak as the\nweakest component, capped at F if a live takeover is found), a one-line\n`summary`, `components` (`email` / `tls` / `headers`, each with its `grade` and\nactionable `issues`), a `tech` section (detected technologies + any version\ndisclosure), and a `takeover` section when the apex is at risk. Uses a fast\nsingle-handshake TLS check for speed — call `tls_check` for the full\ncipher/vulnerability analysis. The best starting point; use the tools below for\nraw detail.\n\n### `dns_recon(domain, checks?, timeout?) -> dict`\n\n- **records** — A, AAAA, MX, NS, TXT, SOA, CNAME, CAA records\n- **whois** — parsed registration fields + raw WHOIS text\n- **email** — SPF, DMARC, and DKIM posture, plus advisory **MTA-STS**,\n  **TLS-RPT**, **BIMI**, and **DNSSEC** signals, and a graded `assessment`\n  (letter grade A–F, a summary, and per-check findings with severity and a\n  recommended fix). The advisory signals surface as findings but don't move the\n  core SPF/DKIM/DMARC grade.\n\n`checks` is any subset of `[\"records\", \"whois\", \"email\"]`; omit it to run all.\n\n### `subdomain_enum(domain, wordlist?, source=\"dns\", timeout?) -> dict`\n\nDiscovers subdomains from two complementary sources:\n- `source=\"dns\"` (default) — resolves candidate labels via DNS. `wordlist` is\n  comma-separated labels (`\"www,api,dev\"`); omit it for a built-in common list.\n  Capped at 512 candidates per call. Returns resolved `ips`.\n- `source=\"ct\"` — queries public **Certificate Transparency** logs (crt.sh) for\n  every name ever certified for the domain. Fully passive; finds real hosts no\n  wordlist would guess.\n- `source=\"both\"` — runs both and merges, recording which source(s) saw each host.\n\nReturns `sources`, `found_count`, and `found` (each with `subdomain`, the\n`sources` that saw it, and `ips` when resolved).\n\n### `subdomain_takeover(hosts, timeout?) -> dict`\n\nChecks subdomains for a **dangling-CNAME takeover** — a subdomain that CNAMEs to\na third-party service (GitHub Pages, S3, Heroku, Azure, Fastly, Shopify, …)\nwhose resource was deleted or never claimed, letting anyone who registers that\nresource serve content on the victim's subdomain. For each host it resolves the\nCNAME, recognizes known takeover-prone services, fetches the page, and flags\nthe provider's \"unclaimed resource\" fingerprint and/or a CNAME target that no\nlonger resolves. `hosts` is one hostname or a comma-separated list (capped at\n100). Read-only — DNS lookups plus one HTTP GET per host. Pair it with\n`subdomain_enum`: enumerate first, then check the interesting hosts.\n\nReturns `checked`, `vulnerable_count`, and `results` (each with `host`, `cname`,\n`service`, `status`, `vulnerable`, `severity`, and `detail`). `status` is one of\n`not_applicable`, `not_vulnerable`, `potential`, `dangling_cname`, or\n`vulnerable`.\n\n### `tls_check(host, port=443, timeout?) -> dict`\n\nReturns `grade`, `certificate` (validity / expiry / key algorithm),\n`protocols` (flags legacy SSLv3 / TLS 1.0 / 1.1), cipher info,\n`forward_secrecy`, `hsts`, `vulnerabilities` (each with a `vulnerable` flag),\nand a `findings` list.\n\n### `http_headers_audit(host, port?, use_ssl=True, timeout?) -> dict`\n\nReturns `grade`, `score`, the observed security headers, and a `findings`\nlist with a recommendation per header. Defaults to HTTPS (port 443).\n\n### `cookie_audit(host, port?, use_ssl=True, timeout?) -> dict`\n\nFollows the redirect chain from the host (capped at 10 hops, flagging any\nHTTPS→HTTP downgrade) and audits every `Set-Cookie` seen for the `Secure`,\n`HttpOnly`, and `SameSite` flags. Returns `redirect_chain`, `final_url`,\n`cookies` (flags only — values are never returned), `cookie_grade`,\n`cookie_score`, and a `findings` list.\n\n### `cors_check(host, port?, use_ssl=True, timeout?) -> dict`\n\nSends one GET with an untrusted `Origin` and inspects the\n`Access-Control-Allow-Origin` / `-Allow-Credentials` response. Reflecting an\narbitrary Origin **with** credentials is high severity (any site can read\nauthenticated responses); a wildcard or trusted `null` origin are lesser issues.\nReturns `acao`, `allows_credentials`, `reflects_origin`, `wildcard`, `severity`,\nand `findings`.\n\n### `tech_detect(host, port?, use_ssl=True, timeout?) -> dict`\n\nFingerprints the technology stack behind a website from **one HTTP GET**. It\nmatches response headers, set cookies, the HTML body, and the\n`<meta name=\"generator\">` tag against a signature table to identify the web\nserver, reverse proxy / CDN, WAF, programming language, web framework, CMS,\nJavaScript framework, and analytics. Where a version is exposed it is captured\nand flagged (`info`) — a precise version eases known-CVE lookup. Read-only.\n\nReturns `status`, `technology_count`, `technologies` (each with `name`,\n`category`, `version` when known, and `evidence`), and a `findings` list noting\nany version disclosure.\n\n### `http_methods_audit(host, port?, use_ssl=True, path=\"/\", timeout?) -> dict`\n\nReports which HTTP request methods a server allows and grades the risk. Enabled\nwrite/diagnostic methods widen the attack surface: **TRACE** enables Cross-Site\nTracing (XST), and **PUT** / **DELETE** can allow file upload or deletion under\nweak access control. **Safe by design** — it never sends a mutating request: it\nactively probes only OPTIONS, HEAD, and TRACE (TRACE merely echoes), and reads\nPUT / DELETE / PATCH / CONNECT from the OPTIONS `Allow` header as *advertised*,\nnever invoking them.\n\nReturns `grade`, `score`, `allow_header`, `advertised_methods`, `trace_enabled`,\n`dangerous_methods`, and a `findings` list (each with the method, severity, and a\nrecommendation).\n\n### `well_known_audit(host, timeout?) -> dict`\n\nFetches and parses `security.txt` (RFC 9116, tried at `/.well-known/` then the\nlegacy path) and `robots.txt`. Returns `security_txt` (parsed fields, structural\n`issues`, `location`) and `robots_txt` (`sitemaps`, `disallow`/`allow` paths,\n`user_agents`), each with a `present` flag.\n\n### `ip_info(host, timeout?) -> dict`\n\nResolves the host's IP and looks it up in the public **RDAP** registry (via\nrdap.org's bootstrap to the right RIR). Returns `ip` and `rdap` (`handle`,\n`name`, `country`, `cidr`, `org`, `abuse_email`).\n\n### `port_scan(host, ports?, timeout?) -> dict`\n\nTCP connect scan of a **single** host. `ports` is a string — `\"22,80,443\"`, a\nrange `\"1-1024\"`, or a mix — and omitting it scans a built-in common-port set.\nHard-capped at 1024 ports per call (single-host recon, not mass scanning).\nReturns `host`, `ip`, `scanned`, `open_count`, and `open_ports` (port +\nservice). Scan only hosts you are authorized to assess.\n\n## License\n\n[MIT](./LICENSE)\n\n<!-- mcp-name: io.github.nan786521/recon-kit-mcp -->\n",
  "bytes": 11345,
  "sha": "9e5937dfe9ba82d58a4bc391b13a2aa6de966ab7fb025790a35361fa27ea31b4",
  "repo_slug": "nan786521/recon-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nan786521_recon_kit_mcp_d95cd458/readme"
}