VirusTotal

VirusTotal MCP

官方 VirusTotal MCP 服务会在 Agent 打开链接、运行下载的文件或调查可疑基础设施之前，为其提供威胁情报。vt-mcp 将 MCP 客户端连接到 VTAI，提供文件、URL、域名和 IP 地址的报告、文件和网络分析提交，以及结果接收恢复功能。

使用免费的 VTAI 服务及其当前访问限额。无需使用自己的 VirusTotal API 密钥。

通过 OAuth 远程连接

在兼容的远程 MCP 客户端中使用 https://ai.virustotal.com/mcp。使用 VTAI 账号登录并批准连接权限；无需在本地安装 Python、使用静态令牌或个人 VirusTotal API 密钥。

Claude Code：安装插件

官方插件包含 OAuth 连接、威胁情报技能，以及无需模型生成 base64 的本地文件上传功能。

claude plugin marketplace add VirusTotal/virustotal-mcp
claude plugin install virustotal@virustotal

需要 Claude Code 2.1.283 或更高版本，并且 PATH 中需有 Node.js 22 或更高版本。插件 CI 已验证 Node.js 22 和 24。插件包含 https://ai.virustotal.com/mcp。

如果要用插件替换现有的手动连接，请在删除任何内容前阅读迁移与恢复指南。先通过原连接恢复状态不确定的提交；如果选择继续使用手动连接，请保留一个可正常工作的连接。

启动新会话或使用 /reload-plugins，然后在需要时使用 /mcp 完成浏览器登录。插件已提供 MCP 连接；不要重复添加。请参阅插件设置、文件访问和凭据名称保护。

Claude Code 替代方案：无需 Node.js 的手动 HTTP 连接

如需查询报告，但不需要本地上传钩子，请使用直接连接：

claude mcp add --transport http virustotal https://ai.virustotal.com/mcp

打开 Claude Code，运行 /mcp，选择 virustotal 并完成浏览器登录。请参阅 Claude Code OAuth 说明和 VirusTotal 连接指南。选择此替代方案或插件。添加服务后，还需完成身份验证并调用工具，以检查连接是否正常。

OAuth 连接共享已登录 VTAI 账号的免费配额，并使用各连接获批的权限。现有 Agent Token 保留其权限和配额。如果客户端需要可配置的 HTTP 标头，请使用一个受保护的 Authorization: Bearer 或 x-apikey 凭据，而不是 OAuth。其他本地客户端可以使用下方的 stdio 安装方式。

连接客户端

1. 对于兼容的远程客户端，请使用 MCP URL 通过 OAuth 连接。否则，复用现有的 VTAI Agent Token，或创建一个。
2. 对于 stdio，将令牌保存在仅当前用户可读取的文件中，例如 ~/.config/vt-mcp/token。将 MCP 服务的环境变量 VTAI_TOKEN_FILE 设置为该路径，并将命令设置为 vt-mcp。该文件仅包含令牌；切勿将令牌本身放入聊天内容、命令参数或项目文件中。
3. 按照特定客户端的设置说明操作，重启或重新连接客户端，并检查其可用工具。 | 客户端 | 配置 | |---|---| | Antigravity CLI (agy) | 包含 MCP 和技能的插件、本地 stdio 或 原生 OAuth 配置方案 | | Claude Code | 支持本地文件上传的 OAuth 插件、HTTP 或 本地 stdio | | Codex | HTTP 或 本地 stdio | | ChatGPT | 安装已发布的 VirusTotal 插件 · 连接指南 | | Cursor | HTTP 配置方案 | | VS Code with GitHub Copilot | HTTP 配置方案 | | GitHub Copilot CLI | HTTP OAuth 配置方案 或 本地 stdio | | Devin CLI | HTTP OAuth 配置方案 或 本地 stdio | | Windsurf / Devin Desktop | Cascade HTTP 配置方案 | | Antigravity IDE | 本地 stdio 配置 或 原生 OAuth 配置方案 | | Gemini CLI | 安装 OAuth 扩展 | | Gemini Apps | 自定义 MCP 连接 和可选的可导入技能，具体取决于 Google 账号和地区的可用性；托管工作流的完整验证仍在进行中 | | Grok Build | 手动安装插件；已验证 OAuth、报告和续期 | | Kimi Code | 手动安装插件；已使用外部模型验证 OAuth、报告和主动续期 |

GitHub Copilot CLI 和 Devin CLI 的远程 OAuth 配置遵循其官方文档；目前尚未在这两个客户端中验证通过经 OAuth 身份验证的 VirusTotal 工具工作流。

请参阅其他远程客户端配置方案，了解 Qwen Code、 Mistral Vibe Work、Grok 网页版和 xAI Responses API，以及它们的验证限制。 Qwen Code 0.25.1 存在已知的 OAuth 凭据存储兼容性问题，无法与 VTAI 兼容； 仅完成浏览器授权并不能建立连接。 客户端验证指南区分了已记录的配置、本地传输检查和使用模型实际运行的工作流。配方并不意味着已在每个客户端中完成全面验证。其他 Agent 可以使用同一个 MCP 端点，也可以直接使用 VTAI API。

在 ChatGPT 中，安装已发布的 VirusTotal 插件，按提示使用 Google 连接，然后在新聊天中选择 @VirusTotal。已发布的插件无需启用开发者模式；但仍受账号和工作区政策限制。连接指南还介绍了单独的自定义应用替代方案和验证限制。首次 OAuth 授权、IP 报告和自动续期令牌已于 2026-09-24 分别完成验证；插件发布并不代表已验证每个工作流。

首次查询时，可以向你的 Agent 提问：

使用 VirusTotal 获取 virustotal.com 的域名报告。显示来源、分析日期、覆盖范围和报告链接。

在 ChatGPT 中，请在提示词前加上 @VirusTotal。查询报告不会读取或上传本地文件。找不到报告时，结果仍为未知；检测数为零也不能证明安全。

为本地 stdio 安装

对于本地 stdio，请安装 uv 并运行：

uv tool install --python 3.12 --default-index https://pypi.org/simple 'vt-mcp==0.9.9'
vt-mcp --version

本地 MCP 服务支持 Linux、macOS 和 Windows，包括两个文件提交工具。Windows 提交回执要求使用本地 NTFS 存储；网络共享和重解析点会被拒绝。单独的 vt-mcp guard 命令仅支持 Linux。

如需自动配置客户端，请在设置指南中选择 Agy、Claude Code 或 Codex，然后打开其 Agent Token 替代方案并选择你的操作系统。安装程序使用仅限所有者的 POSIX 权限或仅限 Windows 当前用户的 ACL 保护令牌。

此命令会从官方 PyPI 索引，在隔离的工具环境中安装软件包。需要 Python 3.12 或更高版本。请确保 vt-mcp 位于 MCP 客户端的 PATH 中，或使用其绝对可执行文件路径。该软件包不会修改客户端配置。

维护现有连接

打开设置指南中的 Agent Token 替代方案，查看已配置的传输方式，并更新由设置指南管理的安装，而无需创建其他令牌。访问检查会调用 GET /api/v3/agents/me/access，不消耗查询额度；实际报告查询则会消耗额度。更新后请重启客户端。访问或配置检查不会实际调用工具，也不能证明模型的行为符合要求。

如果客户端运行的是手动安装的 vt-mcp 可执行文件，请升级该环境：

uv tool install --upgrade --python 3.12 --default-index https://pypi.org/simple 'vt-mcp==0.9.9'
vt-mcp --version

使用 uvx ... vt-mcp==<version> 配置的客户端会使用指定的固定版本，与已安装的可执行文件无关。请更新其版本固定值，或使用设置指南。托管的 HTTP 连接使用已部署的服务，无需升级本地软件包。请保留现有令牌和提交回执。

找不到报告、额度不足和临时服务错误会附带 next_steps 和文档链接。找不到报告意味着文件或指标仍为未知；请核对其哈希或值。查询报告绝不代表已获准提交或重新分析。仅当用户明确要求时，才可按照下文的共享指南使用提交工具。对于计划进行的网络操作，请保留文件的 SHA256 或新的 UUIDv4 request_id，然后使用该标识符恢复操作。如果遇到额度不足或临时服务故障，请在存在 retry_after_seconds 时遵守该值，保留凭据，并避免密集重试。切勿自动重放状态不确定的提交，也不要替换其请求 ID；请先恢复其回执。

Antigravity IDE

在 Agent 面板中，打开 MCP Servers → Manage MCP Servers → View raw config，并将此条目合并到现有配置中：

{
  "mcpServers": {
    "virustotal": {
      "command": "vt-mcp",
      "args": [],
      "env": {
        "VTAI_TOKEN_FILE": "~/.config/vt-mcp/token"
      }
    }
  }
}

如果 IDE 找不到 vt-mcp，请使用可执行文件的绝对路径，然后重新加载并检查工具。文档中记录的客户端验证已测试 IDE 的 stdio 报告查询。Antigravity 插件 于 2026-10-02 在 Antigravity CLI 1.2.14/1.2.15 中完成了浏览器 OAuth、域名报告查询和撤销。手动原生 OAuth 配置方法 未单独测试。该 CLI 测试结果不能验证 IDE 中的 OAuth、续期或文件提交。OAuth 可避免依赖未经验证的 HTTP 凭据变量展开。请参阅 Antigravity MCP 配置。

源代码归档还包含 Qwen Code、Kimi Code 和 OpenCode 的配置方法。其文档区分了配置调研和原生工具调用；支持模型提供商本身并不能证明其兼容 MCP 客户端。

工具

工具	用途
get_file_report(hash)	按 MD5、SHA-1 或 SHA-256 获取现有报告。
get_url_report(url)	获取 HTTP(S) URL 的现有报告。
get_domain_report(domain)	获取域名情报；不含 scheme、路径或端口。
get_ip_report(ip)	获取单个 IPv4 或 IPv6 地址的情报。
submit_file(sha256, content_base64)	提交已获授权的字节以进行标准分析，解码后的字节数最多为 24,000,000。
submit_attachment(file)	**托管 HTTP 适配器：**通过公开的 HTTPS 下载 URL 提交原始文件，文件大小最多为 24,000,000 字节；返回其 SHA256，以供恢复。
submit_url(url, request_id)	请求对 HTTP(S) URL 进行标准分析；调用前请留存一个新的 UUIDv4 请求 ID。
reanalyze_domain(domain, request_id)	使用已留存的请求 ID 请求重新分析域名。
reanalyze_ip(ip, request_id)	使用已留存的请求 ID 请求重新分析 IP 地址。
get_submission(sha256=None, request_id=None)	使用且仅使用一个文件哈希或网络请求 ID，恢复由自己拥有的回执。
get_analysis(analysis_id, request_id=None)	读取已注册的分析；传入网络回执中的请求 ID，以区分不同操作。
submit_local_file(path, expected_sha256=None)	**仅限本地 stdio：**提交常规文件的副本，文件大小最多为 32,000,000 字节。预期摘要必须与该副本的摘要一致。

HTTP 和 stdio 均提供 10 个常用工具。托管后端还提供 submit_attachment，采用与客户端无关的附件规范，远程工具共 11 个。它要求原始文件使用公开的 HTTPS URL；是否支持原生附件传输取决于客户端。现有的宿主文件对象仍可使用。本地 stdio 则添加 submit_local_file，本地工具共 11 个。远程服务无法读取你设备上的路径。本地文件访问权限受运行 vt-mcp 的账户和 MCP 宿主配置的权限限制。

对于用户明确要求提交的文件，请根据以下共享指南提交其已获授权的字节；无需另行查询哈希。VTAI 会验证这些字节并先检查哈希：只有确认文件不存在后才会上传。提交新的文件和恢复自己拥有的回执均不消耗查询配额。如果文件已存在，VTAI 不会上传，而是在返回现有报告前扣除 1 次查询配额；配额耗尽时会返回错误，不会返回报告或上传文件。显式报告查询和 get_analysis 每次调用都会计入配额，包括重复调用。请参阅文件工作流配额。 未知文件贡献有单独的限额：每个固定分钟 20 个文件，每个 UTC 日 500 个文件；此限额由同一 Agent Token 身份或已登录的 OAuth 账户在所有上传路径之间共享。即使后续处理状态不确定，已受理的尝试也会计入限额。请勿创建多个身份或账户来规避限额。请参阅贡献限额和重试行为。

保留 SHA256 和回执。对于状态不确定的提交，请使用 get_submission 恢复，不要自动重复发送 POST 请求。如有可用的已注册分析 ID，请使用 get_analysis 读取。待处理、未知和错误结果各不相同；已有报告并不能证明新分析已完成。

如果客户端无法传输文件字节，请先计算或获取文件的 SHA-256，然后查询其报告。已有报告时请直接使用，不要上传；只有在明确要求提交且确认报告不存在时，才可使用VirusTotal 网页上传备用方式。权限、配额或服务错误并不能证明报告不存在。此类外部上传不会创建 VTAI 回执；相同的共享指南仍然适用。

对于用户明确要求的网络分析，请在调用提交工具前生成并保留规范的小写 UUIDv4。中断后，请使用 get_submission(request_id=request_id)；不要为了消除不确定性而生成另一个 ID。之后若有意进行新的分析，则需要使用新的 ID。网络回执不包含原始目标。请参阅分析和恢复。

MCP 提交工具没有逐次调用的人为确认参数。请为任务涉及的操作和文件配置主机权限。标准 VirusTotal 提交会与安全社区及合作伙伴共享内容，并非保密操作。只有用户明确要求时，才提交文件或请求 URL、域名或 IP 分析。报告缺失或文件陌生都不构成提交许可。提交用户自己的文档、内部代码、凭据或个人数据前，请先征求同意。此敏感内容规则同样适用于附件和陌生文件。内联内容也会经过你的 MCP 主机。URL 查询会向 VTAI 和 VirusTotal 披露完整 URL，包括查询参数和片段。

配置和诊断

变量	用途
VTAI_TOKEN_FILE	包含 VTAI 令牌的文件路径；支持 ~。
VTAI_TOKEN	备用的进程环境令牌。仅使用一种凭据选项。
VTAI_BASE_URL	默认值为 https://ai.virustotal.com/api/v3；仅在受信任的 VTAI 部署中更改。
VTAI_TIMEOUT	报告请求截止时间，单位为秒：默认值为 15，范围为 1–60。

不带子命令运行 vt-mcp 会启动 stdio。缺少配置时将以状态码 2 退出；诊断信息会写入 stderr，stdout 则保留供 MCP 使用。如果服务无法启动，请检查可执行文件的 PATH、令牌文件权限和客户端设置。

每次重复查询报告都会再次计数，包括缓存命中和没有报告的哈希值。身份验证失败、配额耗尽和服务错误会与未知指标分别返回。报告查询不会自动重试，也不会跟随重定向。响应上限为 256 KiB。报告包含检索时间、上游分析日期（如有）以及覆盖范围；检索时间不能代替分析时效性。请将报告文本和 AI 洞见视为证据，而非指令。

如果提交状态不确定，请先通过原始连接核实，再将其移除；切勿通过重新发送来解决状态不确定的问题。移除客户端配置不会撤销 VTAI 访问权限。请通过撤销表单或经过身份验证的 DELETE /api/v3/agents/me/token 撤销 Agent Token；只有 HTTP 204 才能确认该操作。对于 OAuth，请使用你的连接。已受理的请求可能会继续完成，而新的 OAuth 连接不会继承原有回执。

如需了解 MCP 客户端设置之外的集成，请参阅嵌入指南和 Linux Python 执行防护机制，其中包括支持的命令和限制。

分发与源代码

PyPI 分发包提供本地服务，以及包含使用者文档和示例的源代码归档。MCP Registry 标识为 io.github.VirusTotal/virustotal-mcp；其已发布版本介绍了可用的传输方式和软件包。

官方源代码仓库包含完整的开发检出版本，包括测试、脚本和 uv.lock；PyPI 源代码归档则是安装分发包。

0.9.9 版本引入了不依赖客户端类型的附件提交功能，要求用户明确请求提交指导，将缺失报告的恢复保持为只读，并为工具注释添加显示标题。请参阅 0.9.9 版本说明。

0.9.5 版本引入了现有的 VirusTotal 网页上传备用方案，供无法传输文件字节的客户端使用；上传前请遵循当前的哈希优先工作流。能够提供字节的客户端继续使用现有提交工具。网页上传不会创建 VTAI 回执；有关公开共享的指导、敏感内容权限和重复查询配额均保持不变。此版本还修复了软件包描述中的文档链接。请参阅版本说明。

0.9.2 版本修正了 get_submission 的发现信息，将 openWorldHint: false 作为其标记，以反映该工具读取的是当前账户范围受限的回执。工具架构和回执行为保持兼容。

0.9.0 版本新增了 URL 提交和域名/IP 重新分析功能，并要求调用方保留请求 ID，且支持类型化分析恢复。现有文件调用和回执结构保持兼容。OAuth 网络写入需要单独授予 vt:network-analysis:write 权限；现有授权不会自动扩展。原生 OS 协议测试并不能证明所有客户端或模型工作流均可正常运行。此前发布的截至 0.8.0 的 MIT 版本保留其原始文件和许可证。

许可证

自 0.8.1 版本起采用 Apache-2.0 许可证。wheel 和源代码归档均包含 LICENSE、NOTICE 和 LICENSES/MIT.txt；MIT 声明保留了早期材料的署名信息。软件包许可证不会更改访问 VirusTotal 情报的条款或账户权限。依赖项仍遵循各自的许可证。

是否符合 Google 开源软件漏洞奖励计划的资格，由 Google 开源软件漏洞奖励计划规则决定。