# honeylabshq/honeylabs-mcp [Health: Active]

**Category:** 🔒 Security  
**Repository:** https://github.com/honeylabshq/honeylabs-mcp  
**GitHub Stars:** 2  
**Views:** 7  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/honeylabshq-honeylabs-mcp

## Description
Honeypot threat intelligence for AI agents: 90 days of probe data from a sensor network for IP reputation, scanner classification, CVE probing trends, and JA4/JA4H/HASSH fingerprints. Remote MCP, free tier.

## Tools
Capabilities this server exposes over MCP:

- **search_events_tool** — Individual honeypot events with every field, newest first, filtered by source,
network, port, protocol or fingerprint.

Use when the user wants to see the records themselves: "show me the events from
this IP", "what hit port 443 yesterday", "every request carrying this JA4",
"all RDP traffic regardless of port". Do not use it to judge one address (use
ioc_lookup_tool), to rank or count (use top_attackers_tool or
attack_timeline_tool), to search request text (use payload_search_tool), or for
a CVE (use cve_lookup_tool).

Filters, all optional and combined with AND: source_ip, country (ISO 3166
two-letter code), asn ('AS12345'), dest_port, protocol ('tls', or '' for raw
TCP), app_protocol (detected layer-7 protocol such as 'ssh', 'rdp',
'mssql-tds', 'rtsp', 'smbv1', 'bittorrent' or 'mining', whatever the port),
http_method, request_header (substring of the masked request headers),
source_domain (reverse DNS substring), ja4 or ja3 (exact TLS client
fingerprint), akin (exact HTTP request fingerprint such as
b11cun030_00040014_54d07b6d), has_client_cert (true for clients that presented
an mTLS certificate), ip_version (4 or 6). limit is 1 to 500, default 100.

since and until are ISO-8601 UTC timestamps; the span between them may not
exceed the query window of the caller's plan (https://honeylabs.net/pricing.json).
Each record carries source_ip, country, asn, dest_port, user_agent, url_path,
http_request_headers, tls_client_ja4, tls_client_ja3, tls_client_hello_hex (the
raw ClientHello), ssh_client_hassh, tls_client_cert_subject and issuer,
event_sequence, event_duration, byte counts, network_protocol,
application_protocol and timestamp. TCP events from first-contact sensors only.
- **top_attackers_tool** — Ranked leaderboard over a time window: the top source addresses, networks,
countries, destination ports, user agents, JA4 fingerprints, URL paths, reverse
DNS domains or CVEs by event count.

Use for "who is attacking the most", "top countries hitting port 22", "most
targeted ports this week", "top networks by volume", and with by='cve' for
"which CVEs are being scanned for right now". Do not use it for one known
address (use ioc_lookup_tool), one known network (use asn_enrich_tool), one
known CVE (use cve_lookup_tool), or a trend over time (use
attack_timeline_tool).

by: ip, asn, country, port, user_agent, ja4, url_path, domain or cve (default
ip). limit is 1 to 100, default 20. Optional filters country (ISO code),
dest_port and asn ('AS12345'); add one when the window is long, because an
unfiltered ranking over many days can hit the query memory limit. by='cve'
takes no filters and returns value (the CVE id), title, severity,
actively_exploited (on the CISA KEV catalogue), kev_date_added and counts.
since and until are ISO-8601 UTC, within the plan's query window.
- **ioc_lookup_tool** — Everything the sensors hold on one IP address, a CIDR range, several ranges at
once, or a domain, with our verdict and the reasons for it. Start here for any
question about a specific indicator.

Use for "is this IP malicious", "is this a known scanner", "have you seen this
address", "when was it last seen", "have any of this vendor's ranges touched
you". Do not use it to rank many sources (use top_attackers_tool), to profile a
whole ASN (use asn_enrich_tool), or to list raw events (use
search_events_tool). For what an address did inside sessions with the
interactive sensors, follow up with interactive_sessions_tool.

Returns total_events (0 means never observed in the window), first_seen,
last_seen, country, ASN, the 50 most-hit ports with ports_targeted_count, top
user agents and URL paths, TLS/HTTP/SSH fingerprints, cve_probes (the CVE
signatures it was seen probing), verdict (a sentence), verdict_key (a stable
value to alert on: scanner, tor, malicious, scanning, probing or none),
verdict_why (the signals behind it) and scanner (the identity of a recognised
research scanner, else null). Report the verdict with its reasons. A high
count from a recognised scanner is research traffic, not an attack. A single
address may also carry udp_unverified: UDP traffic that claimed it as source,
which can be forged and never counts against it.

days limits the lookback. Leave it unset for a single address to read every
retained event. A CIDR or domain defaults to 90 days because neither can use
an index; pass days to change that. The response names the window it used in
`window`; quote it with any count.

Pass ranges as one string separated by commas, spaces or newlines
('103.66.28.0/22, 8.34.210.32/27'). Never expand a range into addresses and
loop: one call answers it, and looping burns the daily credits. A range answer
has query_type 'cidr' or 'cidr_set', per_range counts and top_source_ips.
- **cve_lookup_tool** — Who is probing one named CVE, and how: counts, top probing addresses, networks,
countries, fingerprints, sample request paths and a daily timeline.

Use whenever the user names a CVE: "is CVE-2024-4577 being exploited in the
wild", "who scans for CVE-2023-1389", "has anyone probed this before it was
published". Do not pass a CVE id to payload_search_tool: the id is our label
for a detection pattern and never appears in request text. For the list of
CVEs being probed right now, use top_attackers_tool with by='cve'.

Returns title, severity, actively_exploited and kev (the CISA KEV entry with
date_added, or null), event and unique-address counts across both sensor
types (first_contact_events and interactive_requests split them; an address
both saw counts once), up to `limit` top probing addresses (1 to 25, default
25) with country, ASN and scanner (name and kind of a recognised research or
vendor scanner, else null), top networks and countries, exploiter
fingerprints, sample paths, a daily timeline and `interactive` (what the
interactive sensors recorded of the probes).

window: 24h, 7d (default), 30d or 90d, and on plans with the full history also
180d, 365d or all. observed: false with a note means we hold no detection
pattern for that CVE, which is not evidence that nobody is scanning for it.
- **payload_search_tool** — Literal substring search, ignoring case, over captured request text: URL path,
request body, request headers and event summary.

Use for "find requests to /wp-admin", "which requests carried this user agent
string", "who sent '../../etc/passwd' last week". It matches text that
appeared in the request and nothing else, so these return nothing:
  - a CVE id ('CVE-2024-4577'). Use cve_lookup_tool; this tool rejects CVE ids.
  - a product or vendor name ('Cisco FMC'). Search the path the product
    exposes instead, such as '/ccmadmin'.
  - a description of behaviour ('SQL injection'). Search a marker that
    occurs in the traffic, such as 'UNION SELECT'.
For a fingerprint use fingerprint_search_tool; for events from one source use
search_events_tool.

An empty list is a real answer: no captured request in the window contained
the string. Widen since and until before concluding the activity does not
exist. since and until are ISO-8601 UTC within the plan's query window. limit
is 1 to 100, default 50.
- **attack_timeline_tool** — Event counts over time, in hourly or daily buckets, optionally filtered by
protocol, country or destination port.

Use for "show the trend this week", "was there a spike on port 22", "how has
SSH scanning changed over 30 days". Do not use it to find who caused a spike
(follow up with top_attackers_tool on the same window and filter) or to see
the events themselves (use search_events_tool).

bucket: 'hour' or 'day' (default). filter_protocol: 'tls', or '' for raw TCP.
filter_country: ISO two-letter code. filter_dest_port: a port number. since
and until are ISO-8601 UTC within the plan's query window. Counts are raw
totals from the first-contact sensors.
- **asn_enrich_tool** — Profile of one autonomous system (a hosting provider, ISP or company network)
over a time window: total events, unique addresses, top targeted ports, source
countries, top user agents and the organisation name.

Use for "tell me about AS202425", "what is this hosting provider doing", "is
this network a source of scanning". To attribute one address to its network,
ioc_lookup_tool already returns the ASN; call this one afterwards for the
network's wider behaviour. To rank networks against each other, use
top_attackers_tool with by='asn'.

asn: 'AS12345' or '12345'. since and until are ISO-8601 UTC within the plan's
query window.
- **fingerprint_search_tool** — Events and sources that carried one client fingerprint in a time window.

Use for "have you seen this JA4", "which IPs share this TLS fingerprint",
"find every scanner with this SSH client fingerprint". For how widespread a
fingerprint is and whether it is one operation or a common client, use
fingerprint_population_tool. For HTTP request shapes a few headers away from an
Akin fingerprint, use fingerprint_similar_tool. A JA4 that starts with q comes
from QUIC over UDP and is answered by udp_activity_tool.

fp_type: 'ja4' (TLS client), 'ja3' (legacy TLS client hash, still keyed by
many feeds), 'akin' (HTTP request shape, such as b11cun030_00040014_54d07b6d)
or 'hassh' (SSH client). since and until are ISO-8601 UTC within the plan's
query window. limit is 1 to 200, default 50.
- **fingerprint_similar_tool** — HTTP request shapes within a few headers of one Akin fingerprint, with what
those clients request and call themselves, and the family the fingerprint
belongs to.

Use when an unfamiliar request shape turns up in your own web server, WAF or
proxy logs and you want to know whether it is a known tool or a variant of
one: "what is close to this fingerprint", "is this the same scanner with one
header added". Only Akin fingerprints work here, because a hashed fingerprint
such as JA4 changes completely when one header is added. For the sources that
carried the exact fingerprint, use fingerprint_search_tool.

fingerprint: an Akin token such as b11cun030_00040014_54d07b6d. max_distance:
1 to 4 headers, default 2. limit: 1 to 25 neighbours, default 8.
- **fingerprint_population_tool** — The population behind one client fingerprint over the full retained window:
how many source addresses carry it, across how many networks and countries,
the ports they hit, the top networks, a sample of addresses, and a read on its
shape.

Use for "is this JA4 one botnet or a common tool", "how many networks use this
HASSH", "how concentrated is this fingerprint". The concentration field says
concentrated (many addresses on few networks), dispersed (many networks in one
short burst on one or two ports, a coordinated operation spread thinly on
purpose), spread (a common client) or mixed; concentrated and dispersed both
point to one operator. For the individual events, use
fingerprint_search_tool with a time window.

fp_type: 'ja4' (TLS; a QUIC JA4 starting with q is answered from UDP traffic,
whose sources can be forged), 'akin' (HTTP request shape) or 'hassh' (SSH).
No date range: it reads everything retained.
- **udp_activity_tool** — UDP datagrams sent to the sensors: DNS questions, QUIC client fingerprints and
other UDP probes, with the ports, networks and countries involved.

Use for "who is sending DNS ANY queries", "is anyone querying version.bind",
"have you seen this QUIC JA4", "which UDP ports are probed", "what hits
5060/udp". Every other tool reads TCP only, so UDP questions belong here. A
UDP source address can be forged: treat each address as claimed, never as
evidence against it, and do not feed it to ioc_lookup_tool as proof.

query uses the /udp search grammar: 'qtype:ANY', 'qname:version.bind',
'proto:quic', 'port:5060 country:CN',
'ja4:q13d0310h3_55b375c5d22e_cd85d2d88918' or 'quic:3f1a9c2b7d40'; leave it
empty for the overview. window: 24h, 7d (default) or 30d, shortened to the
plan's query window when that is shorter (window_notice then says so).
samples: 0 to 25 example datagrams, default 10.
- **interactive_credentials_tool** — Plaintext logins captured by the interactive sensors (sensors that answer as a
real service and hold the session): username, password, the service they were
tried on, the outcome and the source address, newest first, plus the pairs
tried most and a per-service breakdown.

Use for "what passwords are attackers trying on SSH", "which credentials did
this IP try", "what logins hit MySQL this week". For whether an address is
hostile overall, use ioc_lookup_tool; for the rest of what it did in its
sessions, use interactive_sessions_tool.

service: a service name such as ssh-password, telnet-login, mysql-login,
rdp-credssp or smb-ntlmssp, or empty for all. source: an address or CIDR, or
empty for all. window: 24h, 7d (default) or 30d, capped at the plan's query
window. limit: 1 to 200, default 50. These records feed no verdict, and
ioc_lookup_tool does not include them.
- **interactive_files_tool** — Files clients handed to the interactive sensors: uploads, mail attachments,
published messages and other artifacts, by SHA-256, with name, size, MIME
type, the sessions that carried them and the VirusTotal verdict when one is
known.

Use for "have you seen this hash", "what files did this IP upload", "which
malware samples reached the honeypots this month". For files referenced by
URL in exploit payloads rather than delivered in a session, use
payload_search_tool with the URL or path.

sha256: one hash, or empty for every file in the window. source: an address
or CIDR, or empty. window: 24h, 7d or 30d (default), capped at the plan's
query window. limit: 1 to 200, default 50.
- **interactive_sessions_tool** — Sessions one address or range held with the interactive sensors: when, which
port and protocol, the service the sensor answered as, the session verdict
(scan, credential or exploit), labels, turns, bytes, duration, CVE ids proven
by the payload, path-only CVE candidates and the download URLs the client
named, newest first, with verdict, service and port breakdowns.

Use after ioc_lookup_tool when the question is what an address did inside a
session: "what did this IP do on the honeypots", "did this range get past a
login", "which exploits did it try". For the logins alone, use
interactive_credentials_tool; for files it delivered, interactive_files_tool.

source is required: an address or CIDR. window: 24h, 7d (default) or 30d,
capped at the plan's query window. limit: 1 to 200, default 50.

## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "honeylabs-mcp": {
    "url": "https://mcp.honeylabs.net/mcp"
  }
}
```

## Documentation

## What honeylabshq/honeylabs-mcp does

HoneyLabs exposes first-hand honeypot observations through MCP for security investigation and threat-intelligence workflows. The dataset records internet probes received by HoneyLabs sensors, including source addresses, network ownership, geography, ports, protocols, request paths, user agents, TLS and SSH fingerprints, HTTP request shapes, CVE detections, and selected interactive-session activity. The retained first-contact data covers the most recent 90 days.

The service is useful when an agent needs evidence about active scanning rather than a generic reputation score. An IP or domain lookup can return when an indicator was seen, what it targeted, fingerprints associated with it, and a verdict with supporting signals. Recognised research scanners are identified separately, so high activity from one does not automatically imply malicious intent.

## How it works

The MCP endpoint is available at `https://mcp.honeylabs.net/mcp` over streamable HTTP. Requests are authenticated with a HoneyLabs key or, for clients supporting the flow, OAuth 2.1 with PKCE and dynamic client registration. Tool names exposed by the server end in `_tool`, such as `ioc_lookup_tool` and `search_events_tool`.

Queries are constrained by the caller's plan. A free key provides 500 credits per day, while response rows consume credits and query windows vary by plan. Most TCP-oriented tools accept ISO-8601 UTC ranges or predefined windows. UDP activity has separate query handling, and UDP source addresses can be forged; they should be treated as claimed sources rather than proof of attribution.

## Setup and configuration

Create an access key through the HoneyLabs dashboard, then add the remote endpoint to an MCP client with an `Authorization: Bearer <your-key>` header. Claude Desktop, Cursor, and Cline use a JSON server entry containing the URL and header. Claude Code can add the endpoint with its HTTP transport command. Gemini CLI can add the server and complete the OAuth flow instead of using a static key.

The service is remote, so no local package installation or runtime configuration is needed. Client configuration should preserve the exact endpoint URL and authentication method selected for the client.

## Tools and capabilities

- `ioc_lookup_tool` investigates an IP, CIDR range, range set, or domain and returns observations, verdict signals, ports, paths, fingerprints, and CVE probes.
- `search_events_tool` returns individual matching honeypot records with filters such as address, ASN, country, port, protocol, fingerprint, and client-certificate presence.
- `top_attackers_tool` ranks sources, networks, countries, ports, user agents, URL paths, fingerprints, domains, or CVEs by event count.
- `attack_timeline_tool` groups first-contact event counts into hourly or daily buckets.
- `asn_enrich_tool` profiles one autonomous system, including organisation, volume, addresses, ports, countries, and user agents.
- `cve_lookup_tool` reports probing activity for a named CVE, including severity, CISA KEV status, sources, fingerprints, paths, and a daily timeline.
- `payload_search_tool` performs case-insensitive literal searches across captured paths, bodies, headers, and event summaries.
- `fingerprint_search_tool`, `fingerprint_similar_tool`, and `fingerprint_population_tool` find exact fingerprint matches, nearby Akin request shapes, and fingerprint distribution patterns.
- `udp_activity_tool` covers DNS, QUIC, and other UDP probes, including QUIC fingerprints and queried ports.
- `interactive_credentials_tool`, `interactive_files_tool`, and `interactive_sessions_tool` examine login attempts, transferred files with known VirusTotal results, and sessions handled by interactive sensors.

## Limitations and notes

The dataset represents traffic received by HoneyLabs' sensors, not all internet activity. Query windows, result limits, and retained history depend on the plan. A CVE lookup with no detection pattern is not evidence that the CVE has never been scanned. UDP observations require extra caution because source addresses may be spoofed, and interactive credentials are recorded separately from indicator verdicts.

_Full upstream README: https://allmcps.com/mcp/honeylabshq-honeylabs-mcp/readme_