virustotal

快速开始 · 工具 · HTTP · 安全 · 故障排除 · 文档

mcp-virustotal 是一个 MCP 服务，可让 AI Agent 访问 VirusTotal v3 API。向你的 Agent 提供哈希值、URL、IP 或域名，即可获取检测报告，以及分析人员会进一步调查的关联信息：联系过的主机、释放的文件、解析记录和威胁行为者。

说明

这是一个独立项目，与 VirusTotal 或 Google 无关。你需要自己的 VirusTotal API 密钥。

主要功能

• 包含关联信息的报告。 文件、URL、IP 和域名报告会通过一次批量 ?relationships= 调用获取关键关联信息，以节省配额。
• 优先使用缓存。 get_url_report 会返回缓存的 VirusTotal 报告，仅在缓存未命中时才提交扫描。
• 关联分析工具。 使用 VTI 风格修饰符（type:peexe positives:5+）进行样本库搜索、汇总沙箱行为，并查询威胁行为者和恶意软件家族集合。
• 完整的关联信息分页。 支持文件、URL、IP 和域名的 100 多种关联类型，并提供游标分页。
• 两种传输方式。 stdio 适用于桌面客户端，HTTP 流式传输适用于共享服务。
• 经过测试。 格式化器和 API 层的单元测试会在 Node 20、22 和 24 上通过 CI 运行。

工作原理

flowchart LR
    A["AI agent<br/>(Claude, Codex, Gemini, VS Code)"] -->|"MCP over stdio or HTTP"| S["mcp-virustotal"]
    S -->|"validate input,<br/>HTTPS + API key"| V["VirusTotal v3 API"]
    V -->|"JSON"| S
    S -->|"formatted report text"| A

快速开始

要求： Node.js 20 或更高版本，以及 VirusTotal API 密钥。

# 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

有关 Claude Desktop、VS Code、Smithery 和从源码运行的说明，请参阅连接客户端。

然后向你的 Agent 提问：“查询 SHA-256 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f（EICAR 测试文件），并显示它释放了哪些文件以及联系了哪些主机。”

工具

共 11 个工具。完整参数和关联列表请参阅工具参考。

分组	工具
报告（包含关联信息）	get_file_report、get_url_report、get_ip_report、get_domain_report
关联信息分页	get_file_relationship、get_url_relationship、get_ip_relationship、get_domain_relationship
搜索和关联分析	search_vt、get_file_behaviour_summary、get_collection

HTTP 流式传输

默认使用 stdio。设置 MCP_TRANSPORT=httpStream 可运行独立的 HTTP 服务：

MCP_TRANSPORT=httpStream MCP_PORT=3000 VIRUSTOTAL_API_KEY=your-key node build/index.js

docker build -t mcp-virustotal .
docker run -p 127.0.0.1:3000:3000 -e VIRUSTOTAL_API_KEY=your-key -e MCP_TRANSPORT=httpStream mcp-virustotal

/health 提供健康检查。

环境变量

变量	默认值	描述
VIRUSTOTAL_API_KEY	(required)	你的 VirusTotal API 密钥
MCP_TRANSPORT	stdio	stdio 或 httpStream
MCP_HOST	localhost	绑定地址（仅限 httpStream）。Docker 镜像设置为 0.0.0.0
MCP_PORT	3000	HTTP 端口（仅限 httpStream）
MCP_ENDPOINT	/mcp	HTTP 端点路径（仅限 httpStream）

安全

警告

HTTP 传输没有身份验证。请将端口限制在 localhost，或置于带身份验证的反向代理之后，否则任何能够访问该端口的人都可以消耗你的 API 配额。

• 在构建任何请求之前，都会使用 zod 架构验证工具参数。
• API 密钥从环境中读取，且只发送给 VirusTotal。
• 查询会将你的指标发送给 VirusTotal。缓存未命中时，URL 扫描会提交该 URL 进行分析。

请私下报告漏洞；参见 SECURITY.md。

故障排除

• API 密钥错误： 密钥通常为 64 个字符，不含空格或引号。更改配置后请重启客户端。
• 429 错误： 公共套餐每分钟允许 4 次请求。
• 日志： 位于软件包目录中的 logs/mcp-virustotal-server.log。

更多内容请参阅故障排除指南。

开发

git clone https://github.com/w0h1v/mcp-virustotal && cd mcp-virustotal
npm ci
npm test                                  # build + unit tests, no key or network
VIRUSTOTAL_API_KEY=your-key npm run smoke # all 11 tools against the real API

冒烟测试会将调用间隔设为 20 s，以遵守公共套餐的限制，不适用于每天只能进行少量查询的免费套餐。请参阅 CONTRIBUTING.md 和更新日志。

许可证

MIT。参见 LICENSE。