Provides comprehensive security analysis tools for querying the VirusTotal API, including URL analysis, file analysis, IP analysis, domain analysis, relationship analysis, and advanced search capabilities across the VirusTotal dataset.
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:
Installing Manually
TBD
Features
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
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:
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:
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:
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:
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 forrelationship
(required): Type of relationship to queryAvailable 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:
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 filerelationship
(required): Type of relationship to queryAvailable 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:
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 analyzerelationship
(required): Type of relationship to queryAvailable 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:
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 analyzerelationship
(required): Type of relationship to queryAvailable 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:
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 stringlimit
(optional, default: 20): Maximum number of results to return per pagecursor
(optional): Continuation cursor for paginationdescriptors_only
(optional): If true, retrieves only object descriptors instead of full objects
Example:
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:
Contributing
Fork the repository
Create a feature branch (
git checkout -b feature/amazing-feature
)Commit your changes (
git commit -m 'Add amazing feature'
)Push to the branch (
git push origin feature/amazing-feature
)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:
Check the documentation
Search existing issues
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
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Provides comprehensive security analysis tools for querying the VirusTotal API, enabling detailed security reports on URLs, files, IP addresses, and domains with automatic relationship data fetching.
Related MCP Servers
- AsecurityAlicenseAqualityA MCP server for querying the VirusTotal API. This server provides tools for scanning URLs, analyzing file hashes, and retrieving IP address reports.Last updated -13183MIT License
- -securityFlicense-qualityA Model Context Protocol server that provides access to Shodan and VirusTotal APIs for cybersecurity analysis, enabling analysts to perform network intelligence operations including host lookups, vulnerability analysis, and threat intelligence gathering.Last updated -16
- -securityAlicense-qualityA comprehensive system that helps organizations track, manage, and respond to security vulnerabilities effectively through features like vulnerability tracking, user management, support tickets, API key management, and SSL certificate management.Last updated -MIT License
- -securityAlicense-qualityA threat intelligence aggregation server that provides unified access to multiple security sources for analyzing indicators (IPs, domains, hashes, URLs) with confidence scoring.Last updated -2MIT License