MCP Censys

mcp-censys is an MCP server based on the Censys Search API, providing real-time domain, IP, and FQDN reconnaissance capabilities. It supports converting natural language queries into precise Censys queries and has built-in MCP prompt templates to guide Claude in analyzing data.

Security Research and data #Domain Reconnaissance #IP Query #MCP Tool #Real-time Analysis .Python

rating : 2.5 points

downloads : 13

update time : 2025-04-29

What is mcp-censys?

mcp-censys is a conversational interface that allows you to query Censys' internet-wide scan data using plain English. It translates your questions into technical queries and presents the results in an easy-to-understand format. The service provides insights about websites, servers, and network infrastructure without requiring technical expertise.

How to use mcp-censys?

Simply ask questions about domains or IP addresses in natural language. The system will automatically query Censys data and organize the results into clear categories such as services, locations, and security information. There is no need to learn complex search syntax.

When to use mcp-censys?

Ideal for: 1) Investigating website infrastructure 2) Discovering connected services 3) Security research 4) Finding new subdomains 5) Understanding server configurations

Key Features

Natural Language QueriesAsk questions in plain English without learning complex search syntax

Comprehensive Domain LookupGet complete information about all IPs, services, and infrastructure associated with a domain

MCP Prompt TemplatesPredefined analysis templates that guide how results are organized and presented for consistency

New Subdomain DiscoveryFind recently observed subdomains through DNS and certificate data

IP Address AnalysisGet detailed information about any IP address including services, location, and ownership

Strengths & Limitations

Strengths

No technical expertise required - ask questions in natural language

Comprehensive data aggregation from multiple sources

Structured presentation of complex technical information

Built-in analysis templates ensure consistent, high-quality results

Lightweight and easy to deploy with Docker

Limitations

Only shows sample records for domains with many results

Subdomain discovery doesn't show true 'first seen' dates

Designed for single-target analysis, not batch processing

Dependent on Censys scan data (may not have real-time updates)

Requires API keys for full functionality

Getting Started

Set up your environment

Install Docker and create a configuration file with your Censys API credentials

Build the Docker image

Create the service container from the provided Dockerfile

Configure your MCP client

Add the service configuration to your Claude Desktop or other MCP client

Start asking questions

Use natural language queries to investigate domains and IP addresses

Example Use Cases

Investigating a Website's InfrastructureUnderstand what servers and services power a particular website

Security AssessmentCheck what ports and services are exposed on a company's network

Subdomain DiscoveryFind new or recently observed subdomains for monitoring purposes

Frequently Asked Questions

Why am I not getting any results?

How current is the data?

Can I scan multiple targets at once?

What are MCP Prompt Templates?

Additional Resources

Censys Python SDK

Official Python library for Censys API

Model Context Protocol

Documentation about MCP architecture

Censys Search API

Information about the underlying API service

🚀 mcp-censys

mcp-censys is an MCP server designed to connect to the Censys Search API. It enables you to retrieve real-time information about domains, IPs, and FQDNs, and offers enhanced MCP prompt templates.

⚠️ Important Note

This tool is for demonstration purposes only. Do not use it in a production environment.

🚀 Quick Start

✨ Features

Connect to the Censys Search API.
Retrieve real-time information about domains, IPs, and FQDNs.
Provide enhanced MCP prompt templates.

📦 Installation

# Clone the repository
git clone https://github.com/yourusername/mcp-censys.git
cd mcp-censys

# Build the Docker image
docker build -t mcp/censys .

# The .env file should contain the following:
CENSYS_API_ID=your_censys_api_id
CENSYS_API_SECRET=your_censys_api_secret

💻 Usage Examples

MCP Configuration

Add the following to your Claude Desktop configuration:

"censys": {
  "command": "docker",
  "args": [
    "run",
    "--rm",
    "-i",
    "--env-file", "/Users/yourname/.env.censys",
    "mcp/censys"
  ]
}

Screenshots

Here are some examples of mcp-censys in action on Claude Desktop:

Domain/FQDN Query: Displays information such as the IP, ASN, subdomains, and services of a domain.
Detailed Domain Query: Returns more detailed domain information, including IP, ASN, BGP, and TLS information.
IP Query: Displays the coordinates, forward and reverse DNS, and service information of an IP.

📚 Documentation

Troubleshooting

No Results Returned

Ensure that the target is publicly visible.
Check your API keys and rate limits.
DNS results depend on Censys' recent observational data.

Performance Tips

Query one domain or IP at a time to improve speed.
Use lookup_domain or lookup_ip for more focused data.

API Response Issues

If you encounter incorrect result formats, ensure you are using the latest version.
The tool handles pagination automatically. lookup_domain collects all available results, while lookup_domain_detailed shows only partial records.

Limitations

new_fqdns does not represent truly "first-seen" FQDNs but is filtered based on the last observation time.
This tool is suitable for single-target analysis and not for batch scanning.
lookup_domain_detailed only displays 3 records to maintain response size.