VirusTotal MCP Server

1# VirusTotal MCP Server
2 
3[![smithery badge](https://smithery.ai/badge/@burtthecoder/mcp-virustotal)](https://smithery.ai/server/@burtthecoder/mcp-virustotal)
4 
5A 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).
6 
7<a href="https://glama.ai/mcp/servers/rcbu34kp5c"><img width="380" height="200" src="https://glama.ai/mcp/servers/rcbu34kp5c/badge" /></a>
8 
9## Quick Start (Recommended)
10 
11### Installing via Smithery
12 
13To install VirusTotal Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@burtthecoder/mcp-virustotal):
14 
15```bash
16npx -y @smithery/cli install @burtthecoder/mcp-virustotal --client claude
17```
18 
19### Installing Manually
20 
211. Install the server globally via npm:
22```bash
23npm install -g @burtthecoder/mcp-virustotal
24```
25 
262. Add to your Claude Desktop configuration file:
27```json
28{
29  "mcpServers": {
30    "virustotal": {
31      "command": "mcp-virustotal",
32      "env": {
33        "VIRUSTOTAL_API_KEY": "your-virustotal-api-key"
34      }
35    }
36  }
37}
38```
39 
40Configuration file location:
41- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
42- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
43 
443. Restart Claude Desktop
45 
46### Using with VS Code
47 
48To use this MCP server in VS Code with GitHub Copilot:
49 
501. Install the server globally via npm:
51```bash
52npm install -g @burtthecoder/mcp-virustotal
53```
54 
552. Create or update your VS Code MCP configuration file at:
56   - macOS/Linux: `~/.vscode/mcp.json`
57   - Windows: `%USERPROFILE%\.vscode\mcp.json`
58 
593. Add the following configuration:
60```json
61{
62  "servers": {
63    "virustotal": {
64      "command": "mcp-virustotal",
65      "env": {
66        "VIRUSTOTAL_API_KEY": "your-virustotal-api-key"
67      }
68    }
69  }
70}
71```
72 
734. Reload VS Code to activate the MCP server
74 
75You can then use the VirusTotal tools through GitHub Copilot in VS Code by referencing the available tools in your prompts.
76 
77## Alternative Setup (From Source)
78 
79If you prefer to run from source or need to modify the code:
80 
811. Clone and build:
82```bash
83git clone <repository_url>
84cd mcp-virustotal
85npm install
86npm run build
87```
88 
892. Add to your Claude Desktop configuration:
90```json
91{
92  "mcpServers": {
93    "virustotal": {
94      "command": "node",
95      "args": ["/absolute/path/to/mcp-virustotal/build/index.js"],
96      "env": {
97        "VIRUSTOTAL_API_KEY": "your-virustotal-api-key"
98      }
99    }
100  }
101}
102```
103 
104## HTTP Streaming Transport
105 
106The 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.
107 
108### Running in HTTP Streaming Mode
109 
110Set the `MCP_TRANSPORT` environment variable to `httpStream`:
111 
112```bash
113MCP_TRANSPORT=httpStream MCP_PORT=3000 VIRUSTOTAL_API_KEY=your-key node build/index.js
114```
115 
116### Environment Variables
117 
118| Variable | Default | Description |
119|---|---|---|
120| `VIRUSTOTAL_API_KEY` | *(required)* | Your VirusTotal API key |
121| `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `httpStream` |
122| `MCP_PORT` | `3000` | HTTP server port (only for `httpStream`) |
123| `MCP_ENDPOINT` | `/mcp` | HTTP endpoint path (only for `httpStream`) |
124 
125### Docker with HTTP Streaming
126 
127```bash
128docker build -t mcp-virustotal .
129docker run -p 3000:3000 \
130  -e VIRUSTOTAL_API_KEY=your-key \
131  -e MCP_TRANSPORT=httpStream \
132  mcp-virustotal
133```
134 
135The server exposes a health check endpoint at `/health` when running in HTTP streaming mode.
136 
137## Features
138 
139- **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
140- **URL Analysis**: Security reports with automatic fetching of contacted domains, downloaded files, and threat actors
141- **File Analysis**: Detailed analysis of file hashes including behaviors, dropped files, and network connections
142- **IP Analysis**: Security reports with historical data, resolutions, and related threats
143- **Domain Analysis**: DNS information, WHOIS data, SSL certificates, and subdomains
144- **Detailed Relationship Analysis**: Dedicated tools for querying specific types of relationships with pagination support
145- **Rich Formatting**: Clear categorization and presentation of analysis results and relationship data
146 
147## Tools
148 
149### Report Tools (with Automatic Relationship Fetching)
150 
151### 1. URL Report Tool
152- Name: `get_url_report`
153- Description: Get a comprehensive URL analysis report including security scan results and key relationships (communicating files, contacted domains/IPs, downloaded files, redirects, threat actors)
154- Parameters:
155  * `url` (required): The URL to analyze
156 
157### 2. File Report Tool
158- Name: `get_file_report`
159- 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)
160- Parameters:
161  * `hash` (required): MD5, SHA-1 or SHA-256 hash of the file
162 
163### 3. IP Report Tool
164- Name: `get_ip_report`
165- Description: Get a comprehensive IP address analysis report including geolocation, reputation data, and key relationships (communicating files, historical certificates/WHOIS, resolutions)
166- Parameters:
167  * `ip` (required): IP address to analyze
168 
169### 4. Domain Report Tool
170- Name: `get_domain_report`
171- Description: Get a comprehensive domain analysis report including DNS records, WHOIS data, and key relationships (SSL certificates, subdomains, historical data)
172- Parameters:
173  * `domain` (required): Domain name to analyze
174  * `relationships` (optional): Array of specific relationships to include in the report
175 
176### Relationship Tools (for Detailed Analysis)
177 
178### 1. URL Relationship Tool
179- Name: `get_url_relationship`
180- Description: Query a specific relationship type for a URL with pagination support. Choose from 17 relationship types including analyses, communicating files, contacted domains/IPs, downloaded files, graphs, referrers, redirects, and threat actors
181- Parameters:
182  * `url` (required): The URL to get relationships for
183  * `relationship` (required): Type of relationship to query
184    - 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
185  * `limit` (optional, default: 10): Maximum number of related objects to retrieve (1-40)
186  * `cursor` (optional): Continuation cursor for pagination
187 
188### 2. File Relationship Tool
189- Name: `get_file_relationship`
190- Description: Query a specific relationship type for a file with pagination support. Choose from 41 relationship types including behaviors, network connections, dropped files, embedded content, execution chains, and threat actors
191- Parameters:
192  * `hash` (required): MD5, SHA-1 or SHA-256 hash of the file
193  * `relationship` (required): Type of relationship to query
194    - 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
195  * `limit` (optional, default: 10): Maximum number of related objects to retrieve (1-40)
196  * `cursor` (optional): Continuation cursor for pagination
197 
198### 3. IP Relationship Tool
199- Name: `get_ip_relationship`
200- Description: Query a specific relationship type for an IP address with pagination support. Choose from 12 relationship types including communicating files, historical SSL certificates, WHOIS records, resolutions, and threat actors
201- Parameters:
202  * `ip` (required): IP address to analyze
203  * `relationship` (required): Type of relationship to query
204    - Available relationships: comments, communicating_files, downloaded_files, graphs, historical_ssl_certificates, historical_whois, related_comments, related_references, related_threat_actors, referrer_files, resolutions, urls
205  * `limit` (optional, default: 10): Maximum number of related objects to retrieve (1-40)
206  * `cursor` (optional): Continuation cursor for pagination
207 
208### 4. Domain Relationship Tool
209- Name: `get_domain_relationship`
210- Description: Query a specific relationship type for a domain with pagination support. Choose from 21 relationship types including SSL certificates, subdomains, historical data, and DNS records
211- Parameters:
212  * `domain` (required): Domain name to analyze
213  * `relationship` (required): Type of relationship to query
214    - 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
215  * `limit` (optional, default: 10): Maximum number of related objects to retrieve (1-40)
216  * `cursor` (optional): Continuation cursor for pagination
217 
218## Requirements
219 
220- Node.js (v20 or later)
221- A valid [VirusTotal API Key](https://www.virustotal.com/gui/my-apikey)
222 
223## Troubleshooting
224 
225### API Key Issues
226 
227If you see "Wrong API key" errors:
228 
2291. Check the log file at `/tmp/mcp-virustotal-server.log` (on macOS) for API key status
2302. Verify your API key:
231   - Should be a valid VirusTotal API key (usually 64 characters)
232   - No extra spaces or quotes around the key
233   - Must be from the API Keys section in your VirusTotal account
2343. After any configuration changes:
235   - Save the config file
236   - Restart Claude Desktop
237   - Check logs for new API key status
238 
239## Development
240 
241To run in development mode with hot reloading:
242```bash
243npm run dev
244```
245 
246## Error Handling
247 
248The server includes comprehensive error handling for:
249- Invalid API keys
250- Rate limiting
251- Network errors
252- Invalid input parameters
253- Invalid hash formats
254- Invalid IP formats
255- Invalid URL formats
256- Invalid relationship types
257- Pagination errors
258 
259## Version History
260 
261- v1.0.0: Initial release with core functionality
262- v1.1.0: Added relationship analysis tools for URLs, files, and IP addresses
263- v1.2.0: Added improved error handling and logging
264- v1.3.0: Added pagination support for relationship queries
265- v1.4.0: Added automatic relationship fetching in report tools and domain analysis support
266- v1.5.0: Migrated to FastMCP framework with HTTP streaming transport support
267 
268## Contributing
269 
2701. Fork the repository
2712. Create a feature branch (`git checkout -b feature/amazing-feature`)
2723. Commit your changes (`git commit -m 'Add amazing feature'`)
2734. Push to the branch (`git push origin feature/amazing-feature`)
2745. Open a Pull Request
275 
276## License
277 
278This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
279