VirusTotal

by emeryray2002

3 stars

Not rated

GitHub Website

About

Bridges to the VirusTotal API for comprehensive threat intelligence, enabling security analysts to analyze file hashes, URLs, domains, and IP addresses with automatically fetched relationship data for complete security overviews.

Details

Author: emeryray2002
Repository: emeryray2002/virustotal-mcp
GitHub stars: 3
License: Apache License 2.0
Categories: AI, Design, Developer Tools, File Management, Frontend, Security
Tags: #web, #integration

- Comprehensive Analysis Reports: Each analysis tool automatically fetches relevant relationship data along with the basic report, providing a complete security overview in a single request
- URL Analysis: Security reports with automatic fetching of contacted domains, downloaded files, and threat actors
- File Analysis: Detailed analysis of file hashes including behaviors, dropped files, and network connections
- IP Analysis: Security reports with historical data, resolutions, and related threats
- Domain Analysis: DNS information, WHOIS data, SSL certificates, and subdomains
- Detailed Relationship Analysis: Dedicated tools for querying specific types of relationships with pagination support
- Advanced Search: VT Intelligence search capabilities for complex queries across the VirusTotal dataset
- Rich Formatting: Clear categorization and presentation of analysis results and relationship data

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name VirusTotal

Command (node, npx, python, etc.) npx
Arguments
- Argument 1 -y
- Argument 2 @highlight/mcp-server
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "virustotal": {
            "command": "npx",
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "env": {}
        }
    }
}

JSON

{
    "mcpServers": {
        "virustotal": {
            "command": "cmd",
            "args": [
                "/c",
                "npx",
                "-y",
                "@highlight/mcp-server"
            ],
            "env": "$29:props:children:props:children:props:mcp:inferred_config:macos:env"
        }
    }
}

JSON

{
    "mcpServers": {
        "virustotal": {
            "command": "npx",
            "args": "$29:props:children:props:children:props:mcp:inferred_config:macos:args",
            "env": "$29:props:children:props:children:props:mcp:inferred_config:macos:env"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "virustotal": {
            "command": "npx",
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "env": {}
        }
    }
}

JSON

{
    "mcpServers": {
        "virustotal": {
            "command": "cmd",
            "args": [
                "/c",
                "npx",
                "-y",
                "@highlight/mcp-server"
            ],
            "env": "$29:props:children:props:children:props:mcp:inferred_config:macos:env"
        }
    }
}

JSON

{
    "mcpServers": {
        "virustotal": {
            "command": "npx",
            "args": "$29:props:children:props:children:props:mcp:inferred_config:macos:args",
            "env": "$29:props:children:props:children:props:mcp:inferred_config:macos:env"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "virustotal": {
            "command": "npx",
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "env": {}
        }
    }
}

JSON

{
    "mcpServers": {
        "virustotal": {
            "command": "cmd",
            "args": [
                "/c",
                "npx",
                "-y",
                "@highlight/mcp-server"
            ],
            "env": "$29:props:children:props:children:props:mcp:inferred_config:macos:env"
        }
    }
}

JSON

{
    "mcpServers": {
        "virustotal": {
            "command": "npx",
            "args": "$29:props:children:props:children:props:mcp:inferred_config:macos:args",
            "env": "$29:props:children:props:children:props:mcp:inferred_config:macos:env"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "virustotal": {
            "command": "npx",
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "env": {}
        }
    }
}

JSON

{
    "mcpServers": {
        "virustotal": {
            "command": "cmd",
            "args": [
                "/c",
                "npx",
                "-y",
                "@highlight/mcp-server"
            ],
            "env": "$29:props:children:props:children:props:mcp:inferred_config:macos:env"
        }
    }
}

JSON

{
    "mcpServers": {
        "virustotal": {
            "command": "npx",
            "args": "$29:props:children:props:children:props:mcp:inferred_config:macos:args",
            "env": "$29:props:children:props:children:props:mcp:inferred_config:macos:env"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "virustotal": {
            "command": "npx",
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "env": {}
        }
    }
}

JSON

{
    "mcpServers": {
        "virustotal": {
            "command": "cmd",
            "args": [
                "/c",
                "npx",
                "-y",
                "@highlight/mcp-server"
            ],
            "env": "$29:props:children:props:children:props:mcp:inferred_config:macos:env"
        }
    }
}

JSON

{
    "mcpServers": {
        "virustotal": {
            "command": "npx",
            "args": "$29:props:children:props:children:props:mcp:inferred_config:macos:args",
            "env": "$29:props:children:props:children:props:mcp:inferred_config:macos:env"
        }
    }
}

From the repository

To install virustotal-mcp for Claude Desktop automatically via Smithery:

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

TBD

`get_url_report`

Get a comprehensive URL analysis report including security scan results and key relationships (communicating files, contacted domains/IPs, downloaded files, redirects, threat actors). Parameters: url (required): The URL to analyze.

`get_file_report`

Get a comprehensive file analysis report using its hash (MD5/SHA-1/SHA-256). Includes detection results, file properties, and key relationships (behaviors, dropped files, network connections, embedded content, threat actors). Parameters: hash (required): MD5, SHA-1 or SHA-256 hash of the file.

`get_ip_report`

Get a comprehensive IP address analysis report including geolocation, reputation data, and key relationships (communicating files, historical certificates/WHOIS, resolutions). Parameters: ip (required): IP address to analyze.

`get_domain_report`

Get a comprehensive domain analysis report including DNS records, WHOIS data, and key relationships (SSL certificates, subdomains, historical data). Parameters: domain (required): Domain name to analyze.

`get_url_relationship`

Query a specific relationship type for a URL with pagination support. Parameters: url (required): The URL to get relationships for; relationship (required): Type of relationship to query; limit (optional, default: 10): Maximum number of related objects to retrieve (1-40); cursor (optional): Continuation cursor for pagination.

`get_file_relationship`

Query a specific relationship type for a file with pagination support. Parameters: hash (required): MD5, SHA-1 or SHA-256 hash of the file; relationship (required): Type of relationship to query; limit (optional, default: 10): Maximum number of related objects to retrieve (1-40); cursor (optional): Continuation cursor for pagination.

`get_ip_relationship`

Query a specific relationship type for an IP address with pagination support. Parameters: ip (required): IP address to analyze; relationship (required): Type of relationship to query; limit (optional, default: 10): Maximum number of related objects to retrieve (1-40); cursor (optional): Continuation cursor for pagination.

`get_domain_relationship`

Query a specific relationship type for a domain with pagination support. Parameters: domain (required): Domain name to analyze; relationship (required): Type of relationship to query; limit (optional, default: 10): Maximum number of related objects to retrieve (1-40); cursor (optional): Continuation cursor for pagination.

`advanced_corpus_search`

Perform advanced searches across the VirusTotal dataset using VT Intelligence query syntax. Parameters: query (required): The VT Intelligence search query string; limit (optional, default: 20): Maximum number of results to return per page; cursor (optional): Continuation cursor for pagination; descriptors_only (optional): If true, retrieves only object descriptors instead of full objects.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "virustotal": {
            "command": "npx",
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "env": {}
        }
    }
}

Macos

{
    "command": "npx",
    "args": [
        "-y",
        "@highlight/mcp-server"
    ],
    "env": []
}

Windows

{
    "command": "cmd",
    "args": [
        "/c",
        "npx",
        "-y",
        "@highlight/mcp-server"
    ],
    "env": "$29:props:children:props:children:props:mcp:inferred_config:macos:env"
}

Linux

{
    "command": "npx",
    "args": "$29:props:children:props:children:props:mcp:inferred_config:macos:args",
    "env": "$29:props:children:props:children:props:mcp:inferred_config:macos:env"
}

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 (TBD)

Installing via Smithery

To install virustotal-mcp for Claude Desktop automatically via Smithery:

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

Installing Manually

TBD

Features

Tools

Report Tools (with Automatic Relationship Fetching)

1. URL Report Tool

- Name: get_url_report - Description: Get a comprehensive URL analysis report including security scan results and key relationships (communicating files, contacted domains/IPs, downloaded files, redirects, threat actors) - Parameters: url (required): The URL to analyze - Example:
await get_url_report(url="http://example.com/suspicious")

2. File Report Tool
- Name: get_file_report - Description: Get a comprehensive file analysis report using its hash (MD5/SHA-1/SHA-256). Includes detection results, file properties, and key relationships (behaviors, dropped files, network connections, embedded content, threat actors) - Parameters: hash (required): MD5, SHA-1 or SHA-256 hash of the file - Example:

await get_file_report(hash="44d88612fea8a8f36de82e1278abb02f")

3. IP Report Tool

- Name: get_ip_report - Description: Get a comprehensive IP address analysis report including geolocation, reputation data, and key relationships (communicating files, historical certificates/WHOIS, resolutions) - Parameters: ip (required): IP address to analyze - Example:
await get_ip_report(ip="8.8.8.8")

4. Domain Report Tool
- Name: get_domain_report - Description: Get a comprehensive domain analysis report including DNS records, WHOIS data, and key relationships (SSL certificates, subdomains, historical data) - Parameters: domain (required): Domain name to analyze - Example:

await get_domain_report(domain="example.com")

Relationship Tools (for Detailed Analysis)

1. URL Relationship Tool

- Name: get_url_relationship - Description: Query a specific relationship type for a URL with pagination support - Parameters: url (required): The URL to get relationships for relationship (required): Type of relationship to query - Available relationships: analyses, comments, communicating_files, contacted_domains, contacted_ips, downloaded_files, graphs, last_serving_ip_address, network_location, referrer_files, referrer_urls, redirecting_urls, redirects_to, related_comments, related_references, related_threat_actors, submissions limit (optional, default: 10): Maximum number of related objects to retrieve (1-40) cursor (optional): Continuation cursor for pagination - Example:

await get_url_relationship(
    url="http://example.com/suspicious",
    relationship="communicating_files",
    limit=20
)

2. File Relationship Tool

- Name: get_file_relationship - Description: Query a specific relationship type for a file with pagination support - Parameters: hash (required): MD5, SHA-1 or SHA-256 hash of the file relationship (required): Type of relationship to query - Available relationships: analyses, behaviours, bundled_files, carbonblack_children, carbonblack_parents, ciphered_bundled_files, ciphered_parents, clues, collections, comments, compressed_parents, contacted_domains, contacted_ips, contacted_urls, dropped_files, email_attachments, email_parents, embedded_domains, embedded_ips, embedded_urls, execution_parents, graphs, itw_domains, itw_ips, itw_urls, memory_pattern_domains, memory_pattern_ips, memory_pattern_urls, overlay_children, overlay_parents, pcap_children, pcap_parents, pe_resource_children, pe_resource_parents, related_references, related_threat_actors, similar_files, submissions, screenshots, urls_for_embedded_js, votes limit (optional, default: 10): Maximum number of related objects to retrieve (1-40) cursor (optional): Continuation cursor for pagination - Example:

await get_file_relationship(
    hash="44d88612fea8a8f36de82e1278abb02f",
    relationship="behaviours",
    limit=20
)

3. IP Relationship Tool

- Name: get_ip_relationship - Description: Query a specific relationship type for an IP address with pagination support - Parameters: ip (required): IP address to analyze relationship (required): Type of relationship to query - Available relationships: comments, communicating_files, downloaded_files, graphs, historical_ssl_certificates, historical_whois, related_comments, related_references, related_threat_actors, referrer_files, resolutions, urls limit (optional, default: 10): Maximum number of related objects to retrieve (1-40) cursor (optional): Continuation cursor for pagination - Example:

await get_ip_relationship(
    ip="8.8.8.8",
    relationship="communicating_files",
    limit=20
)

4. Domain Relationship Tool

- Name: get_domain_relationship - Description: Query a specific relationship type for a domain with pagination support - Parameters: domain (required): Domain name to analyze relationship (required): Type of relationship to query - Available relationships: caa_records, cname_records, comments, communicating_files, downloaded_files, historical_ssl_certificates, historical_whois, immediate_parent, mx_records, ns_records, parent, referrer_files, related_comments, related_references, related_threat_actors, resolutions, soa_records, siblings, subdomains, urls, user_votes limit (optional, default: 10): Maximum number of related objects to retrieve (1-40) cursor (optional): Continuation cursor for pagination - Example:

await get_domain_relationship(
    domain="example.com",
    relationship="historical_ssl_certificates",
    limit=20
)

5. Advanced Search Tool

- Name: advanced_corpus_search - Description: Perform advanced searches across the VirusTotal dataset using VT Intelligence query syntax - Parameters: query (required): The VT Intelligence search query string limit (optional, default: 20): Maximum number of results to return per page cursor (optional): Continuation cursor for pagination descriptors_only (optional): If true, retrieves only object descriptors instead of full objects - Example:

await advanced_corpus_search(
    query="type:peexe size:100kb+ positives:5+",
    limit=20,
    cursor=None
)

Requirements

- Python >= 3.11
- A valid VirusTotal API Key
- Required Python packages:
aiohttp >= 3.9.0
mcp[cli] >= 1.4.1
python-dotenv >= 1.0.0
typing-extensions >= 4.8.0

Error Handling

The server includes comprehensive error handling for:
- Invalid API keys
- Rate limiting
- Network errors
- Invalid input parameters
- Invalid hash formats
- Invalid IP formats
- Invalid URL formats
- Invalid relationship types
- Pagination errors

Development

To run in development mode:

python -m virustotal_mcp

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 the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

Acknowledgments

- VirusTotal for providing the API and threat intelligence platform
- The MCP project for the server framework
- Contributors and maintainers

Support

For support, please:
1. Check the documentation
2. Search existing issues
3. Create a new issue if needed

Security

- Never commit API keys or sensitive credentials
- Use environment variables for configuration
- Follow security best practices when handling threat intelligence data

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

get_url_report

get_file_report

get_ip_report

get_domain_report

get_url_relationship

get_file_relationship

get_ip_relationship

get_domain_relationship

advanced_corpus_search

Claude Desktop / Cursor

Macos

Windows

Linux

VirusTotal MCP Server

Quick Start (TBD)

Installing via Smithery

Installing Manually

Features

Tools

Report Tools (with Automatic Relationship Fetching)

1. URL Report Tool

2. File Report Tool

3. IP Report Tool

4. Domain Report Tool

Relationship Tools (for Detailed Analysis)

1. URL Relationship Tool

2. File Relationship Tool

3. IP Relationship Tool

4. Domain Relationship Tool

5. Advanced Search Tool

Requirements

Error Handling

Development

Contributing

License

Acknowledgments

Support

Security

Install

More like this

Sentry

Github

Git

GitLab

Context 7

1Panel

`get_url_report`

`get_file_report`

`get_ip_report`

`get_domain_report`

`get_url_relationship`

`get_file_relationship`

`get_ip_relationship`

`get_domain_relationship`

`advanced_corpus_search`