{
  "markdown": "# VirusTotal MCP Server\n\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)\n[![smithery badge](https://smithery.ai/badge/@burtthecoder/mcp-virustotal)](https://smithery.ai/server/@burtthecoder/mcp-virustotal)\n\nA Model Context Protocol (MCP) server for querying the [VirusTotal API](https://www.virustotal.com/). This server provides comprehensive security analysis tools with automatic relationship data fetching. It integrates seamlessly with MCP-compatible applications like [Claude Desktop](https://claude.ai).\n\n## Quick Start (Recommended)\n\n### Claude Code\n```bash\nclaude mcp add --transport stdio --env VIRUSTOTAL_API_KEY=your-key virustotal -- npx -y @burtthecoder/mcp-virustotal\n```\n\n### Codex CLI\n```bash\ncodex mcp add virustotal --env VIRUSTOTAL_API_KEY=your-key -- npx -y @burtthecoder/mcp-virustotal\n```\n\n### Gemini CLI\n```bash\ngemini mcp add -e VIRUSTOTAL_API_KEY=your-key virustotal npx -y @burtthecoder/mcp-virustotal\n```\n\n### Installing via Smithery\n\nTo install VirusTotal Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@burtthecoder/mcp-virustotal):\n\n```bash\nnpx -y @smithery/cli install @burtthecoder/mcp-virustotal --client claude\n```\n\n### Installing Manually\n\n1. Install the server globally via npm:\n```bash\nnpm install -g @burtthecoder/mcp-virustotal\n```\n\n2. Add to your Claude Desktop configuration file:\n```json\n{\n  \"mcpServers\": {\n    \"virustotal\": {\n      \"command\": \"mcp-virustotal\",\n      \"env\": {\n        \"VIRUSTOTAL_API_KEY\": \"your-virustotal-api-key\"\n      }\n    }\n  }\n}\n```\n\nConfiguration file location:\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n3. Restart Claude Desktop\n\n### Using with VS Code\n\nTo use this MCP server in VS Code with GitHub Copilot:\n\n1. Install the server globally via npm:\n```bash\nnpm install -g @burtthecoder/mcp-virustotal\n```\n\n2. Create or update your VS Code MCP configuration file at:\n   - macOS/Linux: `~/.vscode/mcp.json`\n   - Windows: `%USERPROFILE%\\.vscode\\mcp.json`\n\n3. Add the following configuration:\n```json\n{\n  \"servers\": {\n    \"virustotal\": {\n      \"command\": \"mcp-virustotal\",\n      \"env\": {\n        \"VIRUSTOTAL_API_KEY\": \"your-virustotal-api-key\"\n      }\n    }\n  }\n}\n```\n\n4. Reload VS Code to activate the MCP server\n\nYou can then use the VirusTotal tools through GitHub Copilot in VS Code by referencing the available tools in your prompts.\n\n## Alternative Setup (From Source)\n\nIf you prefer to run from source or need to modify the code:\n\n1. Clone and build:\n```bash\ngit clone <repository_url>\ncd mcp-virustotal\nnpm install\nnpm run build\n```\n\n2. Add to your Claude Desktop configuration:\n```json\n{\n  \"mcpServers\": {\n    \"virustotal\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/mcp-virustotal/build/index.js\"],\n      \"env\": {\n        \"VIRUSTOTAL_API_KEY\": \"your-virustotal-api-key\"\n      }\n    }\n  }\n}\n```\n\n## HTTP Streaming Transport\n\nThe server supports HTTP streaming transport in addition to the default stdio transport. This is useful for running the server as a standalone HTTP service that multiple clients can connect to.\n\n### Running in HTTP Streaming Mode\n\nSet the `MCP_TRANSPORT` environment variable to `httpStream`:\n\n```bash\nMCP_TRANSPORT=httpStream MCP_PORT=3000 VIRUSTOTAL_API_KEY=your-key node build/index.js\n```\n\n### Environment Variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `VIRUSTOTAL_API_KEY` | *(required)* | Your VirusTotal API key |\n| `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `httpStream` |\n| `MCP_PORT` | `3000` | HTTP server port (only for `httpStream`) |\n| `MCP_ENDPOINT` | `/mcp` | HTTP endpoint path (only for `httpStream`) |\n\n### Docker with HTTP Streaming\n\n```bash\ndocker build -t mcp-virustotal .\ndocker run -p 3000:3000 \\\n  -e VIRUSTOTAL_API_KEY=your-key \\\n  -e MCP_TRANSPORT=httpStream \\\n  mcp-virustotal\n```\n\nThe server exposes a health check endpoint at `/health` when running in HTTP streaming mode.\n\n## Features\n\n- **Comprehensive Analysis Reports**: Each analysis tool automatically fetches relevant relationship data along with the basic report using VirusTotal's `?relationships=` query, batched to minimize API calls\n- **URL Analysis**: Cached-report-first lookups with automatic fallback to scanning, plus contacted domains, downloaded files, and threat actors\n- **File Analysis**: Detailed analysis of file hashes including behaviors, dropped files, and network connections\n- **IP Analysis**: Security reports with historical data, resolutions, and related threats\n- **Domain Analysis**: DNS information, WHOIS data, SSL certificates, and subdomains\n- **Detailed Relationship Analysis**: Dedicated tools for querying specific types of relationships with pagination support\n- **Corpus Search**: Free-form search across files, URLs, domains, IPs, and comments, including VTI-style modifier syntax (`type:peexe positives:5+`)\n- **Sandbox Behaviour Summary**: Cross-sandbox merged view of processes, files, registry, network, MITRE ATT&CK, IDS alerts, and signature matches\n- **Threat Collections**: Read APT, malware-family, campaign, and intel-report objects referenced from any report's relationships\n- **Rich Formatting**: Clear categorization and presentation of analysis results and relationship data\n\n## Tools\n\n### Report Tools (with Automatic Relationship Fetching)\n\n### 1. URL Report Tool\n- Name: `get_url_report`\n- Description: Get a comprehensive URL analysis report including security scan results and key relationships (communicating files, contacted domains/IPs, downloaded files, redirects, threat actors). Returns the cached VirusTotal report when available; only submits the URL for scanning and polls for completion on a cache miss\n- Parameters:\n  * `url` (required): The URL to analyze\n\n### 2. File Report Tool\n- Name: `get_file_report`\n- 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)\n- Parameters:\n  * `hash` (required): MD5, SHA-1 or SHA-256 hash of the file\n\n### 3. IP Report Tool\n- Name: `get_ip_report`\n- Description: Get a comprehensive IP address analysis report including geolocation, reputation data, and key relationships (communicating files, historical certificates/WHOIS, resolutions)\n- Parameters:\n  * `ip` (required): IP address to analyze\n\n### 4. Domain Report Tool\n- Name: `get_domain_report`\n- Description: Get a comprehensive domain analysis report including DNS records, WHOIS data, and key relationships (SSL certificates, subdomains, historical data)\n- Parameters:\n  * `domain` (required): Domain name to analyze\n  * `relationships` (optional): Array of specific relationships to include in the report\n\n### Relationship Tools (for Detailed Analysis)\n\n### 1. URL Relationship Tool\n- Name: `get_url_relationship`\n- Description: Query a specific relationship type for a URL with pagination support. Choose from 22 relationship types including analyses, communicating files, contacted domains/IPs, downloaded files, graphs, referrers, redirects, threat actors, collections, and votes\n- Parameters:\n  * `url` (required): The URL to get relationships for\n  * `relationship` (required): Type of relationship to query\n    - Available relationships: analyses, collections, comments, communicating_files, contacted_domains, contacted_ips, downloaded_files, embedded_js_files, graphs, last_serving_ip_address, network_location, referrer_files, referrer_urls, redirecting_urls, redirects_to, related_comments, related_references, related_threat_actors, submissions, urls_related_by_tracker_id, user_votes, votes\n  * `limit` (optional, default: 10): Maximum number of related objects to retrieve (1-40)\n  * `cursor` (optional): Continuation cursor for pagination\n\n### 2. File Relationship Tool\n- Name: `get_file_relationship`\n- Description: Query a specific relationship type for a file with pagination support. Choose from 40 relationship types including behaviors, network connections, dropped files, embedded content, execution chains, and threat actors\n- Parameters:\n  * `hash` (required): MD5, SHA-1 or SHA-256 hash of the file\n  * `relationship` (required): Type of relationship to query\n    - Available relationships: analyses, behaviours, bundled_files, carbonblack_children, carbonblack_parents, ciphered_bundled_files, ciphered_parents, 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\n  * `limit` (optional, default: 10): Maximum number of related objects to retrieve (1-40)\n  * `cursor` (optional): Continuation cursor for pagination\n\n### 3. IP Relationship Tool\n- Name: `get_ip_relationship`\n- Description: Query a specific relationship type for an IP address with pagination support. Choose from 15 relationship types including communicating files, historical SSL certificates, WHOIS records, resolutions, threat actors, and votes\n- Parameters:\n  * `ip` (required): IP address to analyze\n  * `relationship` (required): Type of relationship to query\n    - Available relationships: collections, comments, communicating_files, downloaded_files, graphs, historical_ssl_certificates, historical_whois, related_comments, related_references, related_threat_actors, referrer_files, resolutions, urls, user_votes, votes\n  * `limit` (optional, default: 10): Maximum number of related objects to retrieve (1-40)\n  * `cursor` (optional): Continuation cursor for pagination\n\n### 4. Domain Relationship Tool\n- Name: `get_domain_relationship`\n- Description: Query a specific relationship type for a domain with pagination support. Choose from 24 relationship types including SSL certificates, subdomains, historical data, DNS records, and collections\n- Parameters:\n  * `domain` (required): Domain name to analyze\n  * `relationship` (required): Type of relationship to query\n    - Available relationships: caa_records, cname_records, collections, comments, communicating_files, downloaded_files, graphs, 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, votes\n  * `limit` (optional, default: 10): Maximum number of related objects to retrieve (1-40)\n  * `cursor` (optional): Continuation cursor for pagination\n\n### Search & Pivot Tools\n\n### 1. Corpus Search\n- Name: `search_vt`\n- Description: Search the VirusTotal corpus for files, URLs, domains, IPs, or comments matching a query. Accepts plain IOCs (hash, URL, domain, IP), free text against comments, or VTI-style search modifiers\n- Parameters:\n  * `query` (required): Search query. Examples: a SHA-256 hash, `evil.com`, `8.8.8.8`, `type:peexe size:90kb+ tag:signed positives:5+`\n  * `limit` (optional, default: 20): Maximum number of results (1-300)\n  * `cursor` (optional): Continuation cursor for pagination\n\n### 2. File Behaviour Summary\n- Name: `get_file_behaviour_summary`\n- Description: Get a consolidated sandbox behaviour summary for a file, merged across every sandbox that analyzed it. Returns processes, files, registry, network activity, DNS lookups, MITRE ATT&CK techniques, IDS alerts, and signature matches in a single view — far more useful than iterating individual behaviour reports\n- Parameters:\n  * `hash` (required): MD5, SHA-1 or SHA-256 hash of the file\n\n### 3. Collection Lookup\n- Name: `get_collection`\n- Description: Retrieve a VirusTotal collection by ID. Collections represent threat actors, malware families, campaigns, intel reports, and curated IOC sets — often referenced from the `related_threat_actors` and `collections` relationships on other tools. Optionally include relationships to fetch member IOCs in the same call\n- Parameters:\n  * `id` (required): Collection ID (e.g. `threat-actor--<uuid>`, `malware-family--<id>`)\n  * `relationships` (optional): Array of relationship names to include\n    - Available relationships: autogenerated_graphs, comments, domains, files, ip_addresses, owner, references, related_collections, related_references, threat_actors, urls\n\n## Requirements\n\n- Node.js (v20 or later)\n- A valid [VirusTotal API Key](https://www.virustotal.com/gui/my-apikey)\n\n## Troubleshooting\n\n### API Key Issues\n\nIf you see \"Wrong API key\" errors:\n\n1. Check the log file at `/tmp/mcp-virustotal-server.log` (on macOS) for API key status\n2. Verify your API key:\n   - Should be a valid VirusTotal API key (usually 64 characters)\n   - No extra spaces or quotes around the key\n   - Must be from the API Keys section in your VirusTotal account\n3. After any configuration changes:\n   - Save the config file\n   - Restart Claude Desktop\n   - Check logs for new API key status\n\n## Development\n\nTo run in development mode with hot reloading:\n```bash\nnpm run dev\n```\n\n## Testing\n\n### Unit tests\nRun the formatter test suite (no API key, no network):\n```bash\nnpm test\n```\n\n### Live smoke test\nExercise all 11 tools end-to-end against the real VirusTotal API:\n```bash\nVIRUSTOTAL_API_KEY=your-key npm run smoke\n```\n\nThe smoke test paces calls at 20 s to stay under the 4-requests-per-minute public-tier rate limit. **It is not compatible with heavily reduced free tiers (e.g. 1 lookup/day)** — for those, run a single tool by editing `scripts/smoke-test.mjs` and pick the one you want to verify.\n\n## Error Handling\n\nThe server includes comprehensive error handling for:\n- Invalid API keys\n- Rate limiting\n- Network errors\n- Invalid input parameters\n- Invalid hash formats\n- Invalid IP formats\n- Invalid URL formats\n- Invalid relationship types\n- Pagination errors\n\n## Version History\n\n- v1.0.0: Initial release with core functionality\n- v1.1.0: Added relationship analysis tools for URLs, files, and IP addresses\n- v1.2.0: Added improved error handling and logging\n- v1.3.0: Added pagination support for relationship queries\n- v1.4.0: Added automatic relationship fetching in report tools and domain analysis support\n- v1.5.0: Migrated to FastMCP framework with HTTP streaming transport support\n- v1.6.0: Added `search_vt`, `get_file_behaviour_summary`, `get_collection`, and `get_domain_relationship` tools; synced relationship lists with current VirusTotal v3 docs (drops removed `clues`, adds `collections`/`votes`/`user_votes`/`embedded_js_files`/`urls_related_by_tracker_id` where applicable); `get_url_report` now returns the cached report when available instead of re-scanning on every call; report tools use batched `?relationships=` queries for dramatically fewer API calls\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
  "bytes": 15473,
  "sha": "1a42dbe62843cc0aaeda9408a116fe2e467c60b0b490b3b643d5b307e9b76768",
  "repo_slug": "burtthecoder/mcp-virustotal",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_burtthecoder_virustotal_f819bd57/readme"
}