使用说明

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

Installation

From GitHub

Clone the repository:

git clone https://github.com/Cyreslab-AI/urlhaus-mcp-server.git
cd urlhaus-mcp-server

Install dependencies:
```
npm install
```
Build the server:
```
npm run build
```

From npm (Coming Soon)

npm install -g urlhaus-mcp-server

Configuration

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 results
Data 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 watch

To inspect the server:

npm run inspector

Contributing

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.