securitytrails-mcp
v1.0.1
Published
Unofficial MCP server for the SecurityTrails API — DNS history, subdomain enumeration, WHOIS, SSL certificates and IP intelligence as tools for LLM agents. Not affiliated with SecurityTrails or Recorded Future.
Maintainers
Readme
securitytrails-mcp
An MCP server that gives an LLM agent the SecurityTrails API: DNS history, subdomain enumeration, WHOIS (current and historical), SSL certificates, and IPv4 intelligence — 17 read-only tools.
Built for reconnaissance work where the interesting question is usually "what did this look like before the CDN went up?" rather than "what does it resolve to now?".
Unofficial project. Not affiliated with, endorsed by, or sponsored by SecurityTrails or Recorded Future, Inc. You bring your own SecurityTrails API key and use it under your own agreement with them. See Legal.
Quickstart
You need a SecurityTrails API key — the free tier is enough to try it. Get one at securitytrails.com/app/account/credentials.
Claude Code
claude mcp add securitytrails --env SECURITYTRAILS_API_KEY=your_key -- npx -y securitytrails-mcpClaude Desktop, Cursor, VS Code, and other MCP hosts
{
"mcpServers": {
"securitytrails": {
"command": "npx",
"args": ["-y", "securitytrails-mcp"],
"env": {
"SECURITYTRAILS_API_KEY": "your_key"
}
}
}
}Config file locations: Claude Desktop uses claude_desktop_config.json
(~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows);
Cursor uses ~/.cursor/mcp.json; VS Code uses .vscode/mcp.json in the workspace.
Tools
Every tool is read-only, accepts response_format, and costs one SecurityTrails API query per
call — including per page when paging.
| Tool | What it does | Plan |
| --------------------------------------- | -------------------------------------------------------------- | -------- |
| securitytrails_ping | Check the API key is accepted | Free |
| securitytrails_usage | Month-to-date consumption, allowance, remaining quota | Free |
| securitytrails_domain_details | Current DNS records, hostname counts, registrar metadata | Free |
| securitytrails_subdomains | Known subdomains as fully-qualified hostnames | Free |
| securitytrails_associated | Domains sharing registrant details or infrastructure | Free |
| securitytrails_dns_history | Historical A/AAAA/MX/NS/SOA/TXT records with observation dates | Free |
| securitytrails_whois_current | Current WHOIS record | Free |
| securitytrails_whois_history | Past WHOIS records — often pre-redaction | Free |
| securitytrails_ssl | Certificates issued for a hostname, including SAN entries | Free |
| securitytrails_tags | SecurityTrails classification tags | Free |
| securitytrails_ip_neighbors | Adjacent IPv4 blocks, site counts, sample hostnames | Free |
| securitytrails_ip_whois | Network block registration, owner, abuse contacts | Free |
| securitytrails_search_domains | Search the domain dataset by filter object or DSL query | Free |
| securitytrails_search_ips | Search the IP dataset by filter object or DSL query | Free |
| securitytrails_scroll | Continue a search via its meta.scroll_id, when offered | Varies |
| securitytrails_ip_useragents | User agents observed originating from an IPv4 address | Paid |
| securitytrails_company_associated_ips | IP ranges attributed to a domain's owning organisation | Paid |
Plan column reflects what a free-tier key could reach at the time of writing; SecurityTrails may move endpoints between tiers. The two paid endpoints return a clear plan error rather than a generic failure, so an agent knows to stop retrying:
Your SecurityTrails plan does not permit this endpoint (HTTP 403): This feature is not
available for your subscription package.Response format
Every tool takes response_format:
markdown(default) — a compact summary. Converts the API's raw Unix timestamps to dates, drops null-filled privacy contacts, and appends a pagination footer saying whether more data exists. Typically a fraction of the tokens of the equivalent JSON.json— the untouched upstream payload, for when you need a field the summary omits.
If a payload does not match the shape a renderer expects, the server returns the raw JSON rather than a partial summary. A rendering gap will cost you tokens, never data.
Examples
Finding an origin IP behind a CDN
The current A record is a CDN edge, so ask what it used to be:
> Has example.com always been behind Cloudflare? Check its A record history.// securitytrails_domain_details { "domain": "example.com" }
// securitytrails_dns_history { "domain": "example.com", "type": "a" }The history table shows each IP with the window it was observed in and the hosting organisation — an address that predates the CDN cutover is a candidate origin.
Expanding scope from one domain
> I only know example.com. What else does this organisation own?// securitytrails_whois_current { "domain": "example.com" }
// securitytrails_associated { "domain": "example.com" }
// securitytrails_search_domains { "query": "whois_email = '[email protected]'" }WHOIS gives the registrant email; searching the dataset by that email finds every other domain
registered with it. securitytrails_whois_history is often more productive than the current
record, because older entries predate privacy redaction.
Mining certificates for hostnames
> Find hostnames for example.com that subdomain enumeration might have missed.// securitytrails_subdomains { "domain": "example.com", "limit": 1000 }
// securitytrails_ssl { "domain": "example.com", "status": "all", "include_subdomains": true }SAN entries on expired certificates frequently name internal or staging hosts that no longer
resolve. Use status: "all" — the default valid filter hides exactly the interesting ones.
Profiling an IP
> Who owns 8.8.8.8 and what else is in that block?// securitytrails_ip_whois { "ip": "8.8.8.8" }
// securitytrails_ip_neighbors { "ip": "8.8.8.8" }Quota and performance
SecurityTrails bills per API query against a monthly allowance. securitytrails_usage reports
where you stand. Things worth knowing before pointing an agent at a large target:
securitytrails_subdomainscosts one query regardless of result size. It returns the whole set in a single call, so prefer one call with a highlimitover paging withoffset— paging re-fetches and is billed again. Results default to 100 hostnames withtotal_countandhas_morealways reported, so a truncated result is never mistaken for a complete one.- Paged endpoints cost one query per page.
securitytrails_associated,_dns_history,_ssl,_search_domainsand_search_ipsall bill per page. - The domain and IP datasets accept different DSL fields.
ptr_partandopen_port_80are IP-dataset fields; using them againstsecuritytrails_search_domainsis a syntax error, not an empty result.
Each request has a 30-second timeout and retries twice on 429/5xx/network errors with
exponential backoff (500ms, then 1000ms). Non-transient failures — 400, 401, 403, 404 —
are never retried, so a bad argument costs one query rather than three.
Configuration
| Variable | Default | Purpose |
| ---------------------------- | ------------ | --------------------------------- |
| SECURITYTRAILS_API_KEY | (required) | Your API key |
| SECURITYTRAILS_TIMEOUT_MS | 30000 | Per-attempt request timeout |
| SECURITYTRAILS_MAX_RETRIES | 2 | Retries on 429/5xx/network errors |
If the key is missing the server still starts and still lists its tools, so the host shows it as
healthy; each tool call then returns an error naming the variable to set. This is deliberate — a
server that exits on startup shows up in most hosts as an unexplained crash. The key is validated
by use rather than by a startup ping, so that restarting your editor does not spend quota.
Development
git clone https://github.com/aqhmal/securitytrails-mcp.git
cd securitytrails-mcp
npm install
npm test # 85 tests, no API key needed — the HTTP layer is stubbed
npm run build
npm run format # Prettier, in place
npm run inspect # build, then open the MCP Inspector against the serverThe suite drives a real MCP Client against the server in-process, so tool schemas, argument
validation, rendering and error handling are exercised through the actual protocol rather than by
calling handlers directly. See CONTRIBUTING.md.
Release history is in CHANGELOG.md.
evals/ holds a ten-question evaluation set for checking whether a model can actually accomplish
realistic lookups with these tools.
Security
This is a reconnaissance tool. Only use it against infrastructure you are authorised to investigate.
The API key is read from the environment, sent only to api.securitytrails.com over HTTPS as a
header, and never logged, written to disk, or included in a tool result. Tool arguments are
validated with Zod before any request is made: hostnames must be bare hostnames, IPs must be
IPv4, and identifiers interpolated into request paths are percent-encoded, so a traversal
sequence cannot escape its endpoint.
To report a vulnerability, see SECURITY.md.
Legal
This is an unofficial, community-maintained client. It is not affiliated with, endorsed by, or sponsored by SecurityTrails, Recorded Future, Inc., or Mastercard.
SecurityTrails is a trademark of Recorded Future, Inc. (officially styled SecurityTrails, a Recorded Future Company). The name is used here only to identify the API this software talks to — nominative use — and no claim to the mark, and no sponsorship or endorsement, is made or implied. No SecurityTrails logos or brand assets are included or distributed with this project.
This project is a client. It ships no SecurityTrails data, and it grants you no rights to any. Your use of the API is governed entirely by your own agreement with SecurityTrails / Recorded Future, including their terms of service, your plan's query limits, and any restrictions on storing or redistributing what you retrieve. You are responsible for complying with those terms, and for only running reconnaissance against infrastructure you are authorised to investigate.
The MIT licence below covers this client's own source code and nothing else.
License
MIT © aqhmal
