urlhaus

The URLhaus MCP Server exposes tools that let AI agents perform threat intelligence research against URLhaus data. It provides a set of tools to fetch recent malicious URLs, search and filter URLs by host or signature, and look up malware payloads and related URLs. The server is designed to be queried via MCP tool payloads, where each tool name maps to a specific API-like call against the URLhaus dataset. Typical workflows include pulling the latest malicious URL feeds for quick enrichment, verifying a URL of interest, and investigating associated malware families or payloads to support security investigations and threat hunting. The server also supports payload lookups by hash and allows retrieval of URLs by tags or signatures, enabling structured, repeatable queries for automation.

Prerequisites:

• Node.js 18+ installed on your system
• Git for cloning (optional)

1. Install Node.js dependencies

   • If you are installing from GitHub: git clone https://github.com/Cyreslab-AI/urlhaus-mcp-server.git cd urlhaus-mcp-server

   • Install dependencies: npm install

2. Build the server (if you are developing locally) npm run build

3. Run the MCP server

   • From the built source: node build/index.js

4. Configure MCP integration

   • In your MCP configuration, add the server with the following settings: { "mcpServers": { "urlhaus": { "command": "node", "args": ["/path/to/urlhaus-mcp-server/build/index.js"] } } }

5. Optional: Development commands

   • Watch mode for development: npm run watch
   • Inspect server for debugging: npm run inspector

Notes:

• No API keys are required for URLhaus usage as described in the project documentation.
• When running behind firewalls, ensure outbound access to URLhaus endpoints is allowed.
• If you update the repository, rebuild before starting the server to ensure the latest changes are loaded.

Environment variables and configuration options:

• PORT (optional): Set a custom listening port for the MCP server.
• NODE_ENV: Use production for deployments or development for local testing.
• Ensure the specified path in mcp_config points to the built index.js for the server.

Common issues:

• Module not found errors after npm install: make sure dependencies are installed correctly and the build step has completed.
• Network errors when accessing URLhaus: verify network access and DNS resolution from the host running the MCP server.