MCP Recon

1# mcp-recon
2 
3> **mcp-recon** (formerly Tellix) is a conversational reconnaissance interface and MCP server powered by `httpx` and `asnmap`. Just ask.
4 
5## Overview
6 
7**mcp-recon** bridges the gap between natural language and HTTP infrastructure analysis. It exposes reconnaissance tools through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), allowing you to perform web domain reconnaissance via any compatible AI interface, such as Claude Desktop.
8 
9## Features
10 
11- **Conversational Commands**: Execute reconnaissance through simple text prompts
12- **MCP Server**: Integrates with Claude Desktop or other MCP-compatible tools
13- **Multiple Analysis Modes**: Choose from lite and full reconnaissance levels
14- **Standalone ASN Lookup**: Query IPs, ASNs, or organizations directly
15- **Docker Ready**: Run in an isolated container for security and portability
16- **Powered by `httpx`**: Utilizes ProjectDiscovery's robust reconnaissance tools
17- **Bug Workarounds**: Automatically handles `httpx`'s stdin/stdout leakage issue
18- **MCP Prompts**: Includes predefined prompts like `http_lite_scan` and `katana_command_generator` for streamlined operations
19 
20## What is the Model Context Protocol (MCP)?
21 
22The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open standard developed by Anthropic that enables AI assistants to interact with external tools, systems, and data sources. MCP provides a standardized interface for AI models to access and execute functions, retrieve resources, and utilize prompts, facilitating seamless integration between AI applications and various software environments.
23 
24## MCP Prompts in mcp-recon
25 
26In MCP, a **prompt** is a predefined template that guides AI assistants in performing specific tasks. Prompts can accept dynamic arguments, include context from resources, and chain multiple interactions, enabling structured and efficient workflows.
27 
28**mcp-recon** includes the following prompts:
29 
30- **`http_lite_scan`**: Initiates a quick HTTP scan for basic information about specified targets.
31- **`katana_command_generator`**: Generates optimized Katana crawl commands based on reconnaissance goals and desired thoroughness.
32 
33## Quick Start Guide
34 
35**mcp-recon** provides three main reconnaissance tools:
36 
37### 1. Quick/Lightweight Reconnaissance (`http_lite_recon`)
38 
39Fast, lightweight HTTP fingerprinting that provides essential information with minimal overhead.
40 
41**Example:**
42 
43```
44User: "Using quick http recon, what's the status code for example.com?"
45 
46AI: "I checked example.com and it's currently returning a 200 OK status code, indicating the site is up and functioning normally. It's being served from an Nginx web server on IP 93.184.216.34."
47```
48 
49### 2. Full Reconnaissance (`http_full_recon`)
50 
51Comprehensive metadata collection including page previews, headers, certificates, and technology detection.
52 
53**Example:**
54 
55```
56User: "Using full http recon, what certificates is www.google.com using?"
57 
58AI: "Based on my analysis, www.google.com is using a TLS 1.3 certificate issued by Google Trust Services. The certificate was issued on March 20, 2025, and is valid until June 12, 2025. It was specifically issued for 'www.google.com' and uses the TLS_AES_128_GCM_SHA256 cipher suite."
59```
60 
61### 3. ASN Lookup (`asn_lookup`)
62 
63Standalone lookup of IPs, ASNs, or organization names using ProjectDiscovery's `asnmap` library.
64 
65**Example:**
66 
67```
68User: "Who owns ASN 14421?"
69 
70AI: "ASN 14421 is operated by 'PPLINKNET' in the US."
71```
72 
73## Installation
74 
75```bash
76# Clone the repository
77git clone https://github.com/nickpending/mcp-recon.git
78cd mcp-recon
79 
80# Build the Docker image
81docker build -t mcp/recon -f Dockerfile .
82```
83 
84**mcp-recon** is designed to run as a Docker container to be used with Claude Desktop via the MCP protocol.
85 
86## MCP Configuration
87 
88**mcp-recon** runs as a standalone MCP server. Add it to your MCP configuration like so:
89 
90```json
91"mcp-recon": {
92  "command": "docker",
93  "args": [
94    "run",
95    "--rm",
96    "-i",
97    "mcp/recon"
98  ]
99}
100```
101 
102Using an `.env` file:
103 
104```json
105"mcp-recon": {
106  "command": "docker",
107  "args": [
108    "run",
109    "--rm",
110    "-i",
111    "--env-file", "/Users/yourname/.config/mcp-recon.env",
112    "mcp/recon"
113  ]
114}
115```
116 
117Your `.env` should contain:
118 
119```env
120PDCP_API_KEY=your_projectdiscovery_api_key
121```
122 
123## Troubleshooting
124 
125**No Results Returned**:
126- Domain is publicly accessible
127- You've specified the correct tool (`http_lite_recon`, `http_full_recon`, `asn_lookup`)
128- Target domain isn't blocking scans
129 
130**Performance Issues**:
131- Start with `http_lite_recon` for faster results
132- Scan fewer domains at once for better performance
133 
134## Known Issues
135 
136- **httpx Stdin Leak**: The `httpx` library attempts to read stdin even when used as a library. `mcp-recon` shields `os.Stdin` to prevent interference with MCP.
137- **ASN Silent Failures**: Even when `Asn = true`, `httpx` may fail to enrich IPs. `mcp-recon` includes a fallback using the official `asnmap` Go library.
138 
139## Security Considerations
140 
141- Only scan domains you own or have permission to test
142- The full_recon mode retrieves complete page content — use judiciously
143- Consider rate limiting to avoid impacting target systems
144 
145## Screenshots
146 
147![mcp-recon Screenshot - Quick Recon](docs/tellix-screenshot-01.png)
148> This example shows a quick recon request on `www.google.com`, returning status code, title, server details, and IP address — all from a natural language query.
149 
150![mcp-recon Screenshot - Complete Recon](docs/tellix-screenshot-02.png)
151> This example demonstrates a complete recon on `www.microsoft.com`, including TLS config, headers, CDN, and security observations.
152 
153## Name Change Notice
154 
155This project was formerly known as **Tellix**. It has been renamed to **mcp-recon** to better align with the Model Context Protocol (MCP) naming convention used in security tools. All links to the previous repository name will be redirected to the new name, but you should update your references when possible.
156 
157## License
158 
159MIT License. See `LICENSE` file for full details.
160 
161## References & Related Work
162 
163- [Model Context Protocol SDK](https://modelcontextprotocol.io/introduction)
164- [mcp-go](https://github.com/mark3labs/mcp-go)
165- [httpx](https://github.com/projectdiscovery/httpx)
166- [asnmap](https://github.com/projectdiscovery/asnmap)
167- [Claude Desktop](https://www.anthropic.com)