MCP HubMCP Hub
BurtTheCoder

mcp-virustotal

by: BurtTheCoder

A Model Context Protocol (MCP) server for querying the VirusTotal API.

38created 13/12/2024
Visit
API
VirusTotal

📌Overview

Purpose: The VirusTotal MCP Server is designed to provide comprehensive security analysis tools through the VirusTotal API, offering users automated insights into threats and relationships concerning URLs, files, IP addresses, and domains.

Overview: This MCP server simplifies the process of querying the VirusTotal API, enabling seamless integration with MCP-compatible applications like Claude Desktop. It automatically fetches relationship data, ensuring users gain detailed security insights with minimal requests.

Key Features:

  • Comprehensive Analysis Reports: Automatically fetches relationship data alongside basic security reports for a holistic view of potential threats.

  • Multi-Entity Analysis Tools: Supports detailed reports for URLs, files, IPs, and domains, enriching insights with historical data and relevant connections.

VirusTotal MCP Server

A Model Context Protocol (MCP) server for querying the VirusTotal API. This server provides comprehensive security analysis tools with automatic relationship data fetching. It integrates seamlessly with MCP-compatible applications like Claude Desktop.

Quick Start (Recommended)

Installing via Smithery

To install VirusTotal Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @burtthecoder/mcp-virustotal --client claude

Installing Manually

  1. Install the server globally via npm:
npm install -g @burtthecoder/mcp-virustotal
  1. Add to your Claude Desktop configuration file:
{
  "mcpServers": {
    "virustotal": {
      "command": "mcp-virustotal",
      "env": {
        "VIRUSTOTAL_API_KEY": "your-virustotal-api-key"
      }
    }
  }
}

Configuration file location:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  1. Restart Claude Desktop

Alternative Setup (From Source)

If you prefer to run from source or need to modify the code:

  1. Clone and build:
git clone <repository_url>
cd mcp-virustotal
npm install
npm run build
  1. Add to your Claude Desktop configuration:
{
  "mcpServers": {
    "virustotal": {
      "command": "node",
      "args": ["--experimental-modules", "/absolute/path/to/mcp-virustotal/build/index.js"],
      "env": {
        "VIRUSTOTAL_API_KEY": "your-virustotal-api-key"
      }
    }
  }
}

Features

  • Comprehensive Analysis Reports: Includes relevant relationship data with basic report for complete security overview
  • URL Analysis: Security reports with contacted domains, downloaded files, threat actors
  • File Analysis: Detailed file hash analysis including behaviors, dropped files, and network connections
  • IP Analysis: Reports with historical data, resolutions, and related threats
  • Domain Analysis: DNS, WHOIS, SSL certificates, subdomains
  • Detailed Relationship Analysis: Tools for querying specific relationships with pagination support
  • Rich Formatting: Clear categorization of results and relationship data

Tools

Report Tools (with Automatic Relationship Fetching)

1. URL Report Tool

  • Name: get_url_report
  • Description: Comprehensive URL analysis including security scan results and key relationships (communicating files, contacted domains/IPs, downloaded files, redirects, threat actors)
  • Parameters:
    • url (required): URL to analyze

2. File Report Tool

  • Name: get_file_report
  • Description: File analysis report using hash (MD5/SHA-1/SHA-256), including detection results and key relationships (behaviors, dropped files, network connections, embedded content, threat actors)
  • Parameters:
    • hash (required): File hash

3. IP Report Tool

  • Name: get_ip_report
  • Description: IP analysis report including geolocation, reputation, and key relationships (communicating files, historical certificates/WHOIS, resolutions)
  • Parameters:
    • ip (required): IP address

4. Domain Report Tool

  • Name: get_domain_report
  • Description: Domain analysis report including DNS, WHOIS, SSL certificates, subdomains
  • Parameters:
    • domain (required): Domain name
    • relationships (optional): Array of specific relationships

Relationship Tools (for Detailed Analysis)

1. URL Relationship Tool

  • Name: get_url_relationship
  • Description: Query specific relationship type for a URL with pagination. Types include analyses, communicating files, contacted domains/IPs, downloaded files, graphs, referrers, redirects, threat actors
  • Parameters:
    • url (required): URL
    • relationship (required): Relationship type (e.g., analyses, comments, communicating_files, contacted_domains, etc.)
    • limit (optional, default 10): Number to retrieve (1-40)
    • cursor (optional): Pagination cursor

2. File Relationship Tool

  • Name: get_file_relationship
  • Description: Query specific file relationship type with pagination. Includes behaviors, network connections, dropped files, embedded content, execution chains, threat actors
  • Parameters:
    • hash (required): File hash
    • relationship (required): Relationship type (e.g., analyses, behaviours, bundled_files, contacted_domains, dropped_files, embedded_domains, etc.)
    • limit (optional, default 10)
    • cursor (optional)

3. IP Relationship Tool

  • Name: get_ip_relationship
  • Description: Query IP relationship type with pagination. Types include communicating files, historical SSL certificates, WHOIS, resolutions, threat actors
  • Parameters:
    • ip (required): IP address
    • relationship (required): Relationship type (e.g., comments, communicating_files, downloaded_files, historical_ssl_certificates, resolutions)
    • limit (optional, default 10)
    • cursor (optional)

4. Domain Relationship Tool

  • Name: get_domain_relationship
  • Description: Query domain relationship type with pagination. Types include SSL certificates, subdomains, historical data, DNS records
  • Parameters:
    • domain (required): Domain name
    • relationship (required): Relationship type (e.g., caa_records, cname_records, comments, communicating_files, mx_records, ns_records, subdomains, urls)
    • limit (optional, default 10)
    • cursor (optional)

Requirements

Troubleshooting

API Key Issues

If you see "Wrong API key" errors:

  1. Check the log file at /tmp/mcp-virustotal-server.log (macOS) for API key status
  2. Verify your API key:
    • Valid VirusTotal API key (usually 64 characters)
    • No extra spaces or quotes
    • From the API Keys section in your VirusTotal account
  3. After changes:
    • Save config
    • Restart Claude Desktop
    • Check logs for status

Module Loading Issues

If you see ES module loading warnings:

  1. For global installation: Use the simple Quick Start configuration
  2. For source installation: Include --experimental-modules in args

Development

Run in development mode with hot reloading:

npm run dev

Error Handling

Handles errors such as:

  • Invalid API keys
  • Rate limiting
  • Network errors
  • Invalid inputs (parameters, hashes, IPs, URLs, relationship types)
  • Pagination errors

Version History

  • v1.0.0: Initial release with core functionality
  • v1.1.0: Added relationship analysis tools for URLs, files, IPs
  • v1.2.0: Improved error handling and logging
  • v1.3.0: Pagination support for relationship queries
  • v1.4.0: Automatic relationship fetching in report tools and domain analysis support

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.