urlhaus-mcp-server
Provides access to abuse.ch's URLhaus threat intelligence platform, enabling queries for malicious URLs, host/domain information, malware payloads, and malware tags or signatures.
URLhaus MCP Server
A comprehensive Model Context Protocol (MCP) server that provides access to URLhaus, a project from abuse.ch that collects and shares malicious URLs used for malware distribution. This server enables AI agents to perform threat intelligence research and cybersecurity analysis through the URLhaus database.
Features
This MCP server provides the following tools for querying URLhaus data:
URL Analysis Tools
get_recent_urls: Get the most recent malicious URLs from URLhaus
lookup_url: Get detailed information about a specific URL
search_urls: Search for URLs by various criteria (host, URL, tag, or signature)
Host/Domain Analysis Tools
lookup_host: Get information about URLs hosted on a specific host/domain
Malware Analysis Tools
lookup_payload: Get information about a malware payload by its hash
get_payloads: Get recent malware payloads from URLhaus
get_urls_by_tag: Get URLs associated with a specific malware tag/family
get_urls_by_signature: Get URLs associated with a specific malware signature
Related MCP server: virustotal-mcp-server
Installation
From GitHub
Clone the repository:
git clone https://github.com/Cyreslab-AI/urlhaus-mcp-server.git cd urlhaus-mcp-serverInstall dependencies:
npm installBuild the server:
npm run build
From npm (Coming Soon)
npm install -g urlhaus-mcp-serverConfiguration
Auth-Key (required)
As of abuse.ch's "Community First" changes (effective 2025-06-30), every
request to the URLhaus API must carry an Auth-Key HTTP header. Without
it, the API rejects requests. Get a free key at
auth.abuse.ch, then set it as the
URLHAUS_AUTH_KEY environment variable. This server will not start
without it.
Add the server to your MCP settings configuration:
{
"mcpServers": {
"urlhaus": {
"command": "node",
"args": ["/path/to/urlhaus-mcp-server/build/index.js"],
"env": {
"URLHAUS_AUTH_KEY": "your-auth-key-here"
}
}
}
}Usage Examples
Get Recent Malicious URLs
{
"tool": "get_recent_urls",
"arguments": {
"limit": 50
}
}Look Up a Specific URL
{
"tool": "lookup_url",
"arguments": {
"url": "https://suspicious-domain.com/malware.exe"
}
}Search for URLs by Host
{
"tool": "search_urls",
"arguments": {
"search_term": "malicious-domain.com",
"limit": 100
}
}Get URLs by Malware Family
{
"tool": "get_urls_by_tag",
"arguments": {
"tag": "emotet",
"limit": 50
}
}Look Up Malware Payload
{
"tool": "lookup_payload",
"arguments": {
"hash": "d41d8cd98f00b204e9800998ecf8427e"
}
}API Rate Limits
URLhaus has rate limits to prevent abuse. If you encounter rate limiting, wait before making additional requests.
Data Format
All responses include:
query_status: Status of the API query ("ok" or error message)summary: Human-readable summary of resultsData specific to the query type (URLs, payloads, etc.)
About URLhaus
URLhaus is operated by abuse.ch and provides:
Real-time feed of malicious URLs
Information about malware payloads
Integration with various threat intelligence platforms
Free access to security researchers and defenders
For more information, visit: https://urlhaus.abuse.ch/
Development
To run in development mode:
npm run watchTo inspect the server:
npm run inspectorContributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
URLhaus by abuse.ch for providing the free threat intelligence API
Model Context Protocol for the MCP framework
Cyreslab AI for development and maintenance
Support
If you encounter any issues or have questions, please open an issue on GitHub.
Available Tools
7 toolsget_payloadsARead-only
Get recent malware payloads from URLhaus
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of payloads to retrieve (1-1000, default: 100) |
Output Schema
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| payloads | Yes | |
| query_status | Yes | |
| payloads_count | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true, the safety profile is already carried by annotations. The description adds the 'recent' scoping and URLhaus source, but it does not disclose behavioral details such as default limit behavior, pagination, ordering, or API-specific quirks. It is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence states the action, object, and source with no filler or redundant wording. It is as concise as a useful description can be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one optional parameter, an output schema, and read-only annotations. The description covers the core behavior and source sufficiently. It could be slightly more complete by explicitly contrasting with lookup_payload, but nothing essential about invoking the tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single optional 'limit' parameter with range and default, so the description does not need to repeat it. However, the description also adds nothing about how 'limit' relates to 'recent', so it earns the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Get recent malware payloads') plus a clear source ('URLhaus'). This distinguishes it from siblings like get_recent_urls (URLs, not payloads) and lookup_payload (specific lookup, not recent list).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for fetching a list of recent payloads, but it never states when to prefer this over the six siblings or provides exclusions such as using lookup_payload for a specific hash. The agent must infer usage from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_recent_urlsARead-only
Get the most recent malicious URLs from URLhaus (up to 1000 entries)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of URLs to retrieve (1-1000, default: 100) |
Output Schema
| Name | Required | Description |
|---|---|---|
| urls | Yes | |
| summary | Yes | |
| urls_count | Yes | |
| query_status | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the description's main addition is that results are 'most recent' and limited to 1000 entries. It does not disclose behaviors like external API dependency, freshness guarantees, or pagination, but the openWorld annotation reduces the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. It front-loads the core action and resource, then adds the key limit, and every phrase contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with full schema coverage, an output schema, and read-only/open-world annotations, the description is nearly complete. It only lacks explicit routing context relative to sibling tools, which keeps it just short of a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no parameter-level detail beyond what the schema provides. The limit parameter is fully described in the schema with min, max, and default, so the description earns the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), resource ('most recent malicious URLs'), and source ('URLhaus'), clearly distinguishing it from sibling tools like lookup_url and get_urls_by_tag. It also adds the upper bound of 1000 entries, which sharpens the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for retrieving a recent feed of malicious URLs, but it does not explicitly say when to choose this over lookup_url, get_urls_by_tag, or get_urls_by_signature. There is no when-not-to-use or alternative routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_urls_by_signatureARead-only
Get URLs associated with a specific malware signature
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results to return (1-1000, default: 100) | |
| signature | Yes | Malware signature name |
Output Schema
| Name | Required | Description |
|---|---|---|
| urls | Yes | |
| summary | Yes | |
| signature | Yes | |
| urls_count | Yes | |
| query_status | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation as read-only and open-world, and the description adds no behavioral caveats such as exact-match semantics, ordering, pagination, or rate limits. It does not contradict the annotations, but it contributes no behavioral detail beyond what they already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler or repetition. Every word contributes to identifying the action, the resource, and the distinguishing filter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only tool with a fully documented input schema, an output schema, and relevant annotations, the description is largely sufficient. The only notable gap is the lack of explicit guidance for choosing it over sibling tools, which is a minor omission here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both 'signature' and 'limit'. The description's phrase 'specific malware signature' merely restates the signature parameter's schema text and adds little new meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the exact operation ('Get URLs') and the filtering resource ('specific malware signature'), which clearly distinguishes it from siblings such as get_urls_by_tag and get_recent_urls. An agent can tell what this tool does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided, and no alternative tool is named. The intended context is implied by the tool name and operation but not stated directly, so the agent must infer when to choose this over sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_urls_by_tagARead-only
Get URLs associated with a specific malware tag/family
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes | Malware tag/family (e.g., "emotet", "trickbot", "cobalt_strike") | |
| limit | No | Number of results to return (1-1000, default: 100) |
Output Schema
| Name | Required | Description |
|---|---|---|
| tag | Yes | |
| urls | Yes | |
| summary | Yes | |
| urls_count | Yes | |
| query_status | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already cover readOnlyHint and openWorldHint, so the basic safety and open-world behavior are handled. The description adds no extra behavioral context such as whether family matching is recursive, how limit/default applies, or the shape of returned results, but it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. Every word earns its place by identifying the operation, resource, and selector.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only lookup with an output schema and full schema coverage, this is nearly sufficient. Small gaps remain: no guidance on sibling-tool selection and no clarification about whether 'family' implies broader matching than an exact tag.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the tag parameter described and exemplified and the limit parameter given range/default semantics. The description only restates the notion of a 'tag/family' and adds no new parameter-level meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Get'), a clear resource ('URLs'), and the key selector ('specific malware tag/family'). This distinguishes it from siblings like get_recent_urls or lookup_url, which operate on different inputs or scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tag/family selector implies when the tool is appropriate, but the description does not explicitly state when to use it versus alternatives such as get_urls_by_signature or get_recent_urls. No exclusions or fallback guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
lookup_hostARead-only
Get information about URLs hosted on a specific host/domain
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | The hostname or domain to look up (e.g., "example.com") |
Output Schema
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| host_info | Yes | |
| urls_count | Yes | |
| query_status | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the non-mutating behavior is covered structurally. The description adds minimal context beyond the host/domain scope and does not disclose details like result limits, pagination, or whether the lookup only returns current URLs. It is consistent with the annotations and adds no contradicting behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, front-loading the action and object. It is appropriately sized for a one-parameter, read-only lookup tool and every word contributes to clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only, one-parameter tool with a full output schema and 100% schema coverage, the description is complete enough for an agent to invoke it correctly. The annotations cover the safety profile, and the schema covers the parameter and output structure, so no additional explanation is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter description already provides a clear meaning with an example ('example.com'). The tool description merely restates 'host/domain' without adding additional semantics. With full schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get information about URLs hosted on a specific host/domain'. This clearly conveys a host-scoped lookup and helps distinguish it from sibling tools like lookup_url, which implies URL-level lookup. However, it does not explicitly name or contrast sibling tools, so it falls just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is appropriate when an agent has a hostname or domain and wants associated URL information. It provides no explicit guidance about when to prefer this tool over alternatives such as lookup_url or get_urls_by_tag, nor does it state when not to use it. The usage context is inferable but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
lookup_payloadARead-only
Get information about a malware payload by its hash
| Name | Required | Description | Default |
|---|---|---|---|
| hash | Yes | MD5 or SHA256 hash of the malware payload |
Output Schema
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| payload_info | Yes | |
| query_status | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety and completeness profile. The description adds no extra behavioral context beyond the lookup mechanism, which is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence communicates the purpose without any filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single required parameter, a full output schema, and annotations covering read-only and open-world behavior, the description is complete for an agent to call the tool correctly. No additional context is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameter with a clear description ('MD5 or SHA256 hash of the malware payload'). The description merely restates 'by its hash' without adding format or syntax details, so it does not go beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), resource ('information about a malware payload'), and the lookup key ('by its hash'). This clearly distinguishes it from sibling tools like lookup_url and lookup_host, which operate on different identifiers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the use case clear: call this tool when you have a hash of a malware payload. It doesn't explicitly name alternatives or exclusions, but the context of sibling tool names provides enough differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
lookup_urlARead-only
Get detailed information about a specific URL
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL to look up (must be a complete URL with protocol) |
Output Schema
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| url_info | Yes | |
| query_status | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description adds no conflicting behavior. It adds little extra behavioral context beyond 'get detailed information,' but for a simple read-only lookup with an output schema, the annotation coverage makes this acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. It front-loads the operation and object: 'Get detailed information about a specific URL.'
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one fully documented required parameter, read-only annotations, and an output schema present, the description is nearly sufficient for correct invocation. What is missing is only comparative guidance against sibling tools, which is already addressed in other dimensions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the url parameter including the requirement for a complete URL with protocol. The description only restates 'specific URL' and adds no meaningful details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear operation ('get') and resource ('detailed information about a specific URL'), and 'specific' helps separate it from bulk listing tools like get_recent_urls and get_urls_by_tag. However, 'detailed information' is generic and does not convey what kind of details are returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'a specific URL' implies this tool is for looking up one exact URL rather than recent or tagged lists, but there is no explicit guidance on when to choose this over lookup_host or lookup_payload. No exclusions or alternative conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
7 tool updates
v1.0.0- First observed
get_payloads - First observed
get_recent_urls - First observed
get_urls_by_signature - First observed
get_urls_by_tag - First observed
lookup_host - First observed
lookup_payload - First observed
lookup_url
TDQS
Scored across 7 tools
Each tool targets a distinct resource or query mode: URL, host, payload, tag, and signature are clearly separated. The only mild ambiguity is between get_urls_by_tag and get_urls_by_signature, since both return filtered URL lists, but their descriptions clarify the filter type.
Mostly follows a pattern where 'lookup_' means retrieve by a specific identifier/key and 'get_' means retrieve list-style data. However, get_urls_by_tag and get_urls_by_signature are also keyed queries but use 'get_' rather than 'lookup_', creating a minor inconsistency.
Seven tools is well-scoped for a URLhaus threat intel server. Each tool maps to a distinct endpoint or query type, and none feels redundant or out of place.
The set covers the core read-only URLhaus workflows: recent URLs, recent payloads, URL/host/payload lookups, and URL filtering by tag or signature. A minor gap is the lack of payloads-by-tag or payloads-by-signature queries, but most main investigation paths are covered.
Maintenance
Related MCP Connectors
URLhaus MCP — wraps abuse.ch URLhaus malware URL database (free, no auth)
MCP server for ScanMalware.com URL scanning, malware detection, and analysis.
Cybersecurity MCP server for URL scanning, threat intelligence, and domain reputation.
VirusTotal MCP — file / URL / domain / IP reputation (BYO key)
Related MCP Servers
- AlicenseAqualityBmaintenanceA MCP server for querying the VirusTotal API. This server provides tools for scanning URLs, analyzing file hashes, and retrieving IP address reports.11374 npm149MIT
- FlicenseAqualityDmaintenanceMCP server for security analysis using VirusTotal API, enabling AI assistants to analyze URLs, files, IP addresses, and domains with automatic relationship fetching.81-
- FlicenseNot gradedqualityDmaintenanceMCP server that checks URLs against the URLhaus malware database to identify malicious URLs.-
- AlicenseNot gradedqualityCmaintenanceWraps abuse.ch URLhaus malware URL database (free, no auth) – enables querying malware URLs via natural language through Pipeworx MCP gateway.2 npmMIT