Skip to content
Back to search

mcp-virustotal

MCP server for VirusTotal API — analyze URLs, files, IPs, and domains with comprehensive security reports, relationship analysis, and pagination support.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/w0h1v/mcp-virustotal with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/w0h1v/mcp-virustotal'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/w0h1v--mcp-virustotal/badge.svg)](/listings/w0h1v--mcp-virustotal)

HTML

<a href="/listings/w0h1v--mcp-virustotal"><img src="/api/listings/w0h1v--mcp-virustotal/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code

claude mcp add --transport stdio --env VIRUSTOTAL_API_KEY=your-key virustotal -- npx -y @burtthecoder/mcp-virustotal

Codex CLI

codex mcp add virustotal --env VIRUSTOTAL_API_KEY=your-key -- npx -y @burtthecoder/mcp-virustotal

Gemini CLI

gemini mcp add -e VIRUSTOTAL_API_KEY=your-key virustotal npx -y @burtthecoder/mcp-virustotal

Installing via Smithery

To install VirusTotal Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@burtthecoder/mcp-virustotal):

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

Using with VS Code

To use this MCP server in VS Code with GitHub Copilot:

1. Install the server globally via npm:

npm install -g @burtthecoder/mcp-virustotal

2. Create or update your VS Code MCP configuration file at: - macOS/Linux: `~/.vscode/mcp.json` - Windows: `%USERPROFILE%\.vscode\mcp.json`

3. Add the following configuration:

{
  "servers": {
    "virustotal": {
      "command": "mcp-virustotal",
      "env": {
        "VIRUSTOTAL_API_KEY": "your-virustotal-api-key"
      }
    }
  }
}

4. Reload VS Code to activate the MCP server

You can then use the VirusTotal tools through GitHub Copilot in VS Code by referencing the available tools in your prompts.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 135 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.png">
  4. <img alt="mcp-virustotal: threat intelligence for AI agents" src="docs/assets/banner-light.png" width="800">
  5. </picture>
  6. </p>
  7. <p align="center">
  8. <a href="https://www.npmjs.com/package/@burtthecoder/mcp-virustotal"><img alt="npm version" src="https://img.shields.io/npm/v/@burtthecoder/mcp-virustotal"></a>
  9. <a href="https://github.com/w0h1v/mcp-virustotal/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/w0h1v/mcp-virustotal/actions/workflows/ci.yml/badge.svg"></a>
  10. <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
  11. <img alt="Node 20 or newer" src="https://img.shields.io/badge/node-%E2%89%A520-339933">
  12. <a href="https://registry.modelcontextprotocol.io"><img alt="MCP Registry" src="https://img.shields.io/badge/MCP-Registry-7c3aed"></a>
  13. </p>
  14. <p align="center">
  15. <a href="#quickstart">Quickstart</a> ·
  16. <a href="#tools">Tools</a> ·
  17. <a href="#http-streaming-transport">HTTP</a> ·
  18. <a href="#security">Security</a> ·
  19. <a href="#troubleshooting">Troubleshooting</a> ·
  20. <a href="https://w0h1v.github.io/mcp-virustotal/">Docs</a>
  21. </p>
  22. **mcp-virustotal** is an [MCP](https://modelcontextprotocol.io) server that gives AI agents access to the [VirusTotal v3 API](https://docs.virustotal.com/reference/overview). Hand your agent a hash, URL, IP or domain and get back the detection report plus the relationships an analyst would pivot on: contacted hosts, dropped files, resolutions, threat actors.
  23. > [!NOTE]
  24. > Independent project, not affiliated with VirusTotal or Google. You need your own [VirusTotal API key](https://www.virustotal.com/gui/my-apikey).
  25. ## Highlights
  26. - **Reports with relationships.** File, URL, IP and domain reports fetch key relationships in one batched `?relationships=` call to save quota.
  27. - **Cache first.** `get_url_report` returns the cached VirusTotal report and only submits a scan on a cache miss.
  28. - **Pivot tools.** Corpus search with VTI-style modifiers (`type:peexe positives:5+`), merged sandbox behaviour summaries, and threat-actor and malware-family collections.
  29. - **Full relationship paging.** 100+ relationship types across files, URLs, IPs and domains, with cursor pagination.
  30. - **Two transports.** stdio for desktop clients, HTTP streaming for a shared service.
  31. - **Tested.** Unit tests for the formatters and API layer run in CI on Node 20, 22 and 24.
  32. ## How it works
  33. ```mermaid
  34. flowchart LR
  35. A["AI agent<br/>(Claude, Codex, Gemini, VS Code)"] -->|"MCP over stdio or HTTP"| S["mcp-virustotal"]
  36. S -->|"validate input,<br/>HTTPS + API key"| V["VirusTotal v3 API"]
  37. V -->|"JSON"| S
  38. S -->|"formatted report text"| A
  39. ```
  40. ## Quickstart
  41. **Requirements:** Node.js 20 or newer and a VirusTotal API key.
  42. ```sh
  43. # Claude Code
  44. claude mcp add --transport stdio --env VIRUSTOTAL_API_KEY=your-key virustotal -- npx -y @burtthecoder/mcp-virustotal
  45. # Codex CLI
  46. codex mcp add virustotal --env VIRUSTOTAL_API_KEY=your-key -- npx -y @burtthecoder/mcp-virustotal
  47. # Gemini CLI
  48. gemini mcp add -e VIRUSTOTAL_API_KEY=your-key virustotal npx -y @burtthecoder/mcp-virustotal
  49. ```
  50. For Claude Desktop, VS Code and running from source, see [Connect a client](docs/clients.md).
  51. Then ask your agent: *"Look up the SHA-256 `275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f` (the EICAR test file) and show what it drops and contacts."*
  52. ## Tools
  53. Eleven tools. Full parameters and relationship lists are in the [tool reference](docs/tools.md).
  54. | Group | Tools |
  55. |---|---|
  56. | Reports (with relationships) | `get_file_report`, `get_url_report`, `get_ip_report`, `get_domain_report` |
  57. | Relationship paging | `get_file_relationship`, `get_url_relationship`, `get_ip_relationship`, `get_domain_relationship` |
  58. | Search and pivot | `search_vt`, `get_file_behaviour_summary`, `get_collection` |
  59. ## HTTP streaming transport
  60. stdio is the default. Set `MCP_TRANSPORT=httpStream` to run a standalone HTTP service:
  61. ```sh
  62. MCP_TRANSPORT=httpStream MCP_PORT=3000 VIRUSTOTAL_API_KEY=your-key node build/index.js
  63. ```
  64. ```sh
  65. docker build -t mcp-virustotal .
  66. docker run -p 127.0.0.1:3000:3000 -e VIRUSTOTAL_API_KEY=your-key -e MCP_TRANSPORT=httpStream mcp-virustotal
  67. ```
  68. A health check is served at `/health`.
  69. ### Environment variables
  70. | Variable | Default | Description |
  71. |---|---|---|
  72. | `VIRUSTOTAL_API_KEY` | *(required)* | Your VirusTotal API key |
  73. | `MCP_TRANSPORT` | `stdio` | `stdio` or `httpStream` |
  74. | `MCP_HOST` | `localhost` | Bind address (`httpStream` only). The Docker image sets `0.0.0.0` |
  75. | `MCP_PORT` | `3000` | HTTP port (`httpStream` only) |
  76. | `MCP_ENDPOINT` | `/mcp` | HTTP endpoint path (`httpStream` only) |
  77. ## Security
  78. > [!WARNING]
  79. > The HTTP transport has **no authentication**. Keep the port on localhost or behind an authenticating reverse proxy, or anyone who can reach it can spend your API quota.
  80. - Tool arguments are validated with zod schemas before any request is built.
  81. - The API key is read from the environment and sent only to VirusTotal.
  82. - Lookups send your indicators to VirusTotal. A URL scan on a cache miss submits that URL for analysis.
  83. Report vulnerabilities privately; see [SECURITY.md](SECURITY.md).
  84. ## Troubleshooting
  85. - **Wrong API key:** the key is usually 64 characters with no spaces or quotes. Restart the client after changing config.
  86. - **429 errors:** the public tier allows 4 requests per minute.
  87. - **Logs:** `logs/mcp-virustotal-server.log` in the package directory.
  88. More in the [troubleshooting guide](docs/troubleshooting.md).
  89. ## Development
  90. ```sh
  91. git clone https://github.com/w0h1v/mcp-virustotal && cd mcp-virustotal
  92. npm ci
  93. npm test # build + unit tests, no key or network
  94. VIRUSTOTAL_API_KEY=your-key npm run smoke # all 11 tools against the real API
  95. ```
  96. The smoke test paces calls at 20 s for the public-tier limit and isn't suited to free tiers reduced to a few lookups a day. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [changelog](CHANGELOG.md).
  97. ## License
  98. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.