📌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 and integrates 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
   

2. 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

3. 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
   

2. 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: Automatically fetch relevant relationship data along with the basic report.
• URL Analysis: Security reports that include contacted domains, downloaded files, and threat actors.
• File Analysis: Detailed analysis of file hashes including behaviors and network connections.
• IP Analysis: Historical data and related threats for IP addresses.
• Domain Analysis: DNS information, WHOIS data, and SSL certificates.
• Rich Formatting: Clear categorization and presentation of analysis results.

Tools

Report Tools

1. URL Report Tool

   • Name: get_url_report
   • Description: Comprehensive URL analysis report.
   • Parameters:
     • url (required)

2. File Report Tool

   • Name: get_file_report
   • Description: Comprehensive file analysis report using hash.
   • Parameters:
     • hash (required)

3. IP Report Tool

   • Name: get_ip_report
   • Description: Comprehensive IP address analysis report.
   • Parameters:
     • ip (required)

4. Domain Report Tool

   • Name: get_domain_report
   • Description: Comprehensive domain analysis report.
   • Parameters:
     • domain (required)
     • relationships (optional)

Relationship Tools

1. URL Relationship Tool

   • Name: get_url_relationship
   • Description: Query a specific relationship type for a URL.
   • Parameters:
     • url (required)
     • relationship (required)

2. File Relationship Tool

   • Name: get_file_relationship
   • Description: Query a specific relationship type for a file.
   • Parameters:
     • hash (required)
     • relationship (required)

3. IP Relationship Tool

   • Name: get_ip_relationship
   • Description: Query a specific relationship type for an IP address.
   • Parameters:
     • ip (required)
     • relationship (required)

4. Domain Relationship Tool

   • Name: get_domain_relationship
   • Description: Query a specific relationship type for a domain.
   • Parameters:
     • domain (required)
     • relationship (required)

Requirements

• Node.js (v18 or later)
• A valid VirusTotal API Key

Troubleshooting

API Key Issues

If you see "Wrong API key" errors, check your API key status in your log file and ensure it's valid.

Module Loading Issues

For loading issues, refer to the configuration to ensure you're including --experimental-modules as needed.

Development

To run in development mode with hot reloading:

npm run dev

Error Handling

The server handles various errors including invalid input parameters and rate limiting.

Version History

• v1.0.0: Initial release
• v1.1.0: Added relationship analysis tools
• v1.2.0: Improved error handling
• v1.3.0: Added pagination support
• v1.4.0: Automatic relationship fetching

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 MIT License.