MCP Censys Server

mcp-censys is a MCP server that taps into the Censys Search API for real-time domain, IP, and FQDN reconnaissance

python

6

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "nickpending-mcp-censys": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        "/Users/yourname/.env.censys",
        "mcp/censys"
      ],
      "env": {
        "CENSYS_API_ID": "YOUR_API_ID",
        "CENSYS_API_SECRET": "YOUR_API_SECRET"
      }
    }
  }
}

You deploy this MCP server to access real-time Censys reconnaissance via natural language prompts. It translates your questions into targeted Censys queries and surfaces host, DNS, cert, and service insights in a Claude-friendly format, all through a lightweight Docker-based runtime.

How to use

Use an MCP client to send natural language prompts to the censys MCP server. You can ask questions like “What’s behind mailchimp.com?” or request a detailed look at all IPs and services for a domain. The server will aggregate data across DNS, TLS, and service observations and present it in organized sections guided by built-in MCP prompts.

How to install

Prerequisites you need on your machine: Docker and a text editor to create environment variables files.

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

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

# Create an environment file with your Censys credentials
# Example content
CENSYS_API_ID=your_censys_api_id
CENSYS_API_SECRET=your_censys_api_secret

Configuration and run

Run the MCP server locally using Docker. The following command starts the container and loads credentials from a named environment file. You can adapt the path to your own environment file accordingly.

docker run --rm -i \
  --env-file /Users/yourname/.env.censys \
  mcp/censys

Note: The environment file should contain CENSYS_API_ID and CENSYS_API_SECRET values as shown in the installation step.

## Troubleshooting and tips

No Results Returned:
- Ensure the target is publicly accessible
- Check your CENSYS\_API\_ID and CENSYS\_API\_SECRET are correct and not rate-limited
- Some results depend on recent observations in Censys datasets
Performance Tips:
- Query a single domain or IP at a time for faster results
- Prefer lookup\_domain or lookup\_ip for focused data
API Response Issues:
- Update to the latest version if result formatting errors occur
- The tools handle pagination; lookup\_domain collects all results, while lookup\_domain\_detailed shows a subset
- For domains with many results, queries may take longer due to multiple API requests

## Available tools

### lookup\_domain

Get comprehensive IPs, DNS names, services, and ASN info for a domain, aggregating data across all results with built-in MCP prompts that organize findings into meaningful sections.

### lookup\_domain\_detailed

Return a sample of 3 host records with services, ASN, geo, TLS data, plus total record count and structured MCP prompts for full infrastructure analysis.

### lookup\_ip

Enrich an IP with DNS names, ASN, service info, and TLS metadata.

### new\_fqdns

Find recently observed FQDNs for a domain from DNS records and certificate visibility.

### host\_services

List open ports and service banners for a given domain or IP.