# Install VirusTotal for your agent Choose one route and reuse existing access. ## Direct REST access For a result in this session or a headless agent, use [the REST quickstart](/skills/BASIC.md). Reuse your Agent Token; register once only if needed. No MCP installation is required. OAuth tokens are MCP-only. ## ChatGPT plugin [Install VirusTotal in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6abadac2d9a08191ae2307c047bb3806). Connect when prompted, continue with Google and approve the permissions. Start a new chat, select @VirusTotal and ask for a domain report. The published plugin does not require Developer mode. Installation and use depend on your ChatGPT account and workspace policies. ## Browser OAuth Server URL: `https://ai.virustotal.com/mcp`. No local server or Agent Token required. Remove manual authentication headers from the server entry when choosing OAuth. [Review or revoke connections](https://ai.virustotal.com/oauth/connections). ### Claude Code Claude Code 2.1.283 or later and Node.js 22 or later. Install the plugin on the machine that holds the file. ```sh claude plugin marketplace add VirusTotal/virustotal-mcp claude plugin install virustotal@virustotal ``` Start a new Claude Code session or run /reload-plugins. Run /mcp and authenticate VirusTotal from the plugin, then continue with Google and approve permissions. Already added VirusTotal with claude mcp add? Keep only one entry. Read Migrating an existing manual connection before removing anything: https://github.com/VirusTotal/virustotal-mcp/blob/main/docs/claude-code.md#replace-an-existing-manual-connection Alternative recipes: manual HTTP without Node.js, or setup with an Agent Token. [Claude setup](/connect/mcp?client=claude&format=markdown). ### Codex ```sh codex mcp add virustotal --url https://ai.virustotal.com/mcp codex mcp login virustotal ``` Complete browser sign-in with Google and approve permissions. Open or reconnect your Codex session to use the server. [Claude / Claude Desktop](/connect/mcp?client=claude-web&format=markdown) · [ChatGPT](/connect/mcp?client=chatgpt&format=markdown) · [Gemini Apps](/connect/mcp?client=gemini&format=markdown) · [Antigravity and Gemini CLI (OAuth)](https://github.com/VirusTotal/virustotal-mcp/blob/main/docs/google-clients.md). ## Choose your MCP client - [Antigravity CLI (agy)](/connect/mcp?client=agy&format=markdown): Official plugin · browser sign-in. Verified: plugin OAuth, a report and revocation. - [Claude Code](/connect/mcp?client=claude&format=markdown): Official plugin · browser sign-in. Verified: plugin OAuth and tool workflows on Linux. - [Codex](/connect/mcp?client=codex&format=markdown): Browser sign-in or Agent Token. Verified in staging: browser sign-in and one direct native report call. - [Cursor](/connect/mcp?client=cursor&format=markdown): Editor and Cursor CLI. Documented setup; VTAI OAuth workflow unverified. - [VS Code](/connect/mcp?client=vscode&format=markdown): Install link · browser sign-in. Documented setup; VTAI OAuth workflow unverified. - [GitHub Copilot CLI](/connect/mcp?client=copilot&format=markdown): Local terminal agent. Documented setup; VTAI OAuth workflow unverified. - [Devin Local / CLI](/connect/mcp?client=devin&format=markdown): Local agent and terminal. Documented setup; VTAI OAuth workflow unverified. - [Cascade / Windsurf](/connect/mcp?client=cascade&format=markdown): Legacy agent in Devin Desktop. Documented setup; native tool calls and model workflow pending. - [Claude / Claude Desktop](/connect/mcp?client=claude-web&format=markdown): Custom connector with browser sign-in. Hosted chat workflow remains unverified. - [ChatGPT](/connect/mcp?client=chatgpt&format=markdown): Published plugin · browser sign-in. Published plugin. Browser sign-in, reports and token renewal verified separately. - [Gemini Apps](/connect/mcp?client=gemini&format=markdown): US, 18+, personal Google accounts. Skill import verified; MCP connection unverified. - [Gemini CLI](/connect/mcp?client=gemini-cli&format=markdown): Official extension; separate model access required. Report verified with supplied credentials; native OAuth unverified. - [Another MCP client](/connect/mcp?client=other&format=markdown): Remote MCP or a protected Agent Token. [Neutral selector](/connect/mcp?format=markdown). Reconnect or start a new session if your client requires it. [Client validation and detailed setup](https://github.com/VirusTotal/virustotal-mcp/blob/main/docs/clients.md). [Grok Build, Kimi Code and other clients](https://github.com/VirusTotal/virustotal-mcp/blob/main/docs/additional-clients.md), including the known Qwen Code OAuth limitation. ## Verify Call `get_domain_report(domain="virustotal.com")` once. An Agent Token can first use `GET /api/v3/agents/me/access` without query cost; this checks authentication only. The actual report uses one query. Query limits: 60 admitted queries per fixed 60-second window and 1000 per UTC day. Agent Tokens share the agent's allowance across REST and MCP; OAuth connections share the account's allowance. Unknown reports and upstream failures after admission count. Every repeated lookup counts again, including cached reports and hashes with no report. On 429, honor Retry-After and reuse your credential. File submissions first check whether the hash exists in VirusTotal. Only confirmed unknown files are uploaded, without using query quota, even when the query allowance is exhausted. A separate file contribution limit permits 20 admitted upload attempts per fixed 60-second window and 500 per UTC day, per Agent Token identity or OAuth account across connections. Failed or uncertain admitted attempts still count; known files and receipt recovery do not. Creating multiple identities or accounts to evade limits is not permitted. If the file is known, returning its existing report costs one query and no file is uploaded. Explicit hash lookups and analysis-result reads still count. The access check costs no query quota and does not report remaining quota. Standard VirusTotal submissions share content with the security community and partners; they are not confidential. Upload files or attachments, submit URLs, or request domain/IP reanalysis only when the user explicitly requests that action. A missing report, an unfamiliar file or a suspicious indicator is not permission to submit it. Explain the sharing and ask before submitting the user's own documents, internal code, credentials or personal data. Submission tools add no per-call confirmation; client permissions still apply. ## Maintain an existing installation For a setup-managed Agent Token installation, download [setup.py](/setup.py) as `vtai-setup.py` and choose the same client as the existing setup. For example, for Agy on macOS/Linux: ```sh python3 vtai-setup.py --client agy --check --json python3 vtai-setup.py --client agy --update --json ``` On Windows use `py -3` instead of `python3`. Review the check before updating. Check spends no report quota. Update preserves credentials and other settings; it never registers. Native OAuth is managed by your client. ## Runtime plugins ### [Antigravity plugin](https://github.com/VirusTotal/virustotal-mcp/blob/main/plugins/antigravity/README.md) Connect Agy to remote VirusTotal MCP with browser sign-in and investigation instructions. The plugin does not add a local file-upload hook. Run these commands once, or reuse your existing checkout and start with validation. Install its plugins/antigravity directory. ```sh git clone https://github.com/VirusTotal/virustotal-mcp.git agy plugin validate ./virustotal-mcp/plugins/antigravity agy plugin install ./virustotal-mcp/plugins/antigravity ``` Run agy plugin list, then authenticate the plugin's virustotal_virustotal server in /mcp. Follow the browser consent and enter any callback code only in the client's authentication dialog. Request an existing report and inspect its tool result. Native Agy sign-in, one domain report and revocation were verified on 2 October 2026; renewal, writes and the graphical IDE remain separate checks. Requires Agy model access. The remote server cannot read a local path; this plugin does not intercept downloads. Keep existing stdio and VT Sentinel IDE configurations unless deliberately replacing them. [Install & permissions](https://github.com/VirusTotal/virustotal-mcp/blob/main/plugins/antigravity/README.md) ### [VT Sentinel for Antigravity IDE](https://open-vsx.org/extension/virustotal/vt-sentinel) Check supported IDE downloads against VirusTotal before the requesting tool receives them. The extension creates VTAI access and stores it in IDE SecretStorage. ```sh antigravity --install-extension virustotal.vt-sentinel ``` Open a workspace. Run VT Sentinel: Run Self-Test, then VT Sentinel: Open Protected Terminal from the Command Palette. This uses the Antigravity IDE CLI, not agy. Run antigravity --list-extensions --show-versions and inspect the self-test. Follow its trust or restart instructions before relying on interception. HTTP(S) interception only. Remote workspaces cover new IDE terminals and tasks. Some systems need a trust approval or managed restart; the self-test shows the effective scope. [Open VSX & setup](https://open-vsx.org/extension/virustotal/vt-sentinel) ### [OpenClaw plugin](https://github.com/king-tero/VT-sentinel) Add file reputation tools and automatic artifact checks to OpenClaw. The plugin creates or reuses VTAI access on first use when no VirusTotal key is configured. ```sh openclaw plugins install clawhub:openclaw-plugin-vt-sentinel ``` Run openclaw gateway restart, then openclaw plugins list. Restart only the gateway you intend to update. Call vt_sentinel_status to inspect active policy, then vt_check_hash with a known file hash for a first reputation lookup. Status alone does not verify access to VTAI. Protection follows the configured scanning, upload and blocking policies. Instruction files default to hash-only; sensitive-file upload behavior is configurable. [Setup & configuration](https://github.com/king-tero/VT-sentinel) ### [Hermes plugin](https://github.com/king-tero/hermes-virustotal) Give Hermes file and hash reputation tools, plus compact advisory context about observed artifacts. Explicit checks create or reuse VTAI access in the active profile. ```sh hermes plugins install king-tero/hermes-virustotal --enable ``` Run hermes plugins list and start a new Hermes session. If using a messaging gateway, restart it with hermes gateway restart. The --enable flag activates the plugin without an interactive enable prompt. Call vt_check_hash with a known file hash, or vt_check_file with a path in the active execution environment. The file check hashes the file without uploading it. Advisory by default; exact-malicious enforcement is optional. Binary-content upload behavior has separate configuration. Text is not auto-uploaded and archives are opt-in. [Setup & configuration](https://github.com/king-tero/hermes-virustotal) ### [VirusTotal for Omarchy](https://github.com/dsecuma/omarchy-virustotal) A community plugin for the Omarchy Quattro desktop: look up files, hashes, URLs, domains and IPs, optionally monitor downloads and installed plugins, and connect supported coding agents to VirusTotal. Maintained by David Santos · dsecuma. ```sh omarchy plugin add https://github.com/dsecuma/omarchy-virustotal.git --enable ``` Requires Omarchy Quattro. Open the VirusTotal panel and press Connect to create or reuse VTAI access; no VirusTotal API key is needed. Download monitoring and plugin scanning are off by default; enable them separately in Settings if wanted. In the Scan tab, look up virustotal.com and inspect the report and its date. Check access verifies authentication only. Coding agents use separate OAuth sign-in; some require manual setup in the guide. Local files are checked by hash. Manual uploads require confirmation; automatic uploads of unknown plugin files require a separate opt-in. Uploads are standard, non-private VirusTotal submissions. Download monitoring never uploads files. Alerts do not block execution, and zero detections do not establish safety. [View on Omarchy Marketplace](https://plugins.omarchy.org/plugin.html?id=io.github.dsecuma.virustotal) · [Source & setup](https://github.com/dsecuma/omarchy-virustotal) [Operations and interpretation](/?format=markdown) · [OpenAPI](/openapi.json) · [Deduplicated file lookup example](/examples/query_file_reports.py).