Metadata-Version: 2.4
Name: vt-mcp
Version: 0.8.3
Summary: VirusTotal intelligence for MCP clients, powered by VTAI
Author: VirusTotal
License-Expression: Apache-2.0
License-File: LICENSE
License-File: LICENSES/MIT.txt
License-File: NOTICE
Requires-Dist: anyio>=4.15.1,<5
Requires-Dist: httpx>=0.28.1,<0.29
Requires-Dist: mcp==2.1.1
Requires-Dist: pydantic>=2.13.5,<3
Requires-Python: >=3.12
Project-URL: Homepage, https://ai.virustotal.com
Project-URL: Documentation, https://ai.virustotal.com/install.md
Project-URL: Repository, https://github.com/VirusTotal/virustotal-mcp
Project-URL: Issues, https://github.com/VirusTotal/virustotal-mcp/issues
Description-Content-Type: text/markdown

# VirusTotal MCP

<!-- mcp-name: io.github.VirusTotal/virustotal-mcp -->

Give your agent VirusTotal intelligence before it opens a link, runs a downloaded file or investigates suspicious infrastructure. **vt-mcp** connects MCP clients to [VTAI](https://ai.virustotal.com), with reports for files, URLs, domains and IP addresses, file submission and analysis recovery.

Use the free VTAI service with its current access limits. You need a **VTAI token**, available from [connection setup](https://ai.virustotal.com/connect/mcp); you do not need your own VirusTotal API key. Both local and remote connections use the same account rights and quotas.

## Install for local stdio

For local stdio, install [uv](https://docs.astral.sh/uv/getting-started/installation/) and run:

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

The command installs the package from the official PyPI index in an isolated tool environment. Python 3.12 or newer is required. Keep `vt-mcp` on the MCP client's PATH, or use its absolute executable path. The package does not modify client configuration.

For a connection without a local Python process, use **`https://ai.virustotal.com/mcp`** with a supported HTTP client. Supply the VTAI token through either `Authorization: Bearer` or `x-apikey`, using the client's protected credential settings. Send only one authentication header. This is static token authentication; clients that require OAuth need a separate integration.

## Connect your client

1. Reuse your existing VTAI access or [create a token](https://ai.virustotal.com/connect/mcp).
2. For stdio, save the token in a file readable only by your user, such as `~/.config/vt-mcp/token`. Set the MCP server's environment variable `VTAI_TOKEN_FILE` to that path and its command to `vt-mcp`. The file contains only the token; never put the token itself in chat, command arguments or project files.
3. Follow the client-specific setup, restart or reconnect the client, and inspect its available tools.

| Client | Setup |
|---|---|
| Antigravity CLI (`agy`) | [Local stdio](https://ai.virustotal.com/connect/mcp?client=agy&transport=stdio) |
| Claude Code | [HTTP](https://ai.virustotal.com/connect/mcp?client=claude&transport=http) or [local stdio](https://ai.virustotal.com/connect/mcp?client=claude&transport=stdio) |
| Codex | [HTTP](https://ai.virustotal.com/connect/mcp?client=codex&transport=http) or [local stdio](https://ai.virustotal.com/connect/mcp?client=codex&transport=stdio) |
| Cursor | [HTTP recipe](https://ai.virustotal.com/connect/mcp?client=cursor&transport=http) |
| VS Code with GitHub Copilot | [HTTP recipe](https://ai.virustotal.com/connect/mcp?client=vscode&transport=http) |
| GitHub Copilot CLI | [Local stdio recipe](https://ai.virustotal.com/connect/mcp?client=copilot&transport=stdio) |
| Devin Local | [Local stdio recipe](https://ai.virustotal.com/connect/mcp?client=devin&transport=stdio) |
| Windsurf / Devin Desktop | [Cascade HTTP recipe](https://ai.virustotal.com/connect/mcp?client=cascade&transport=http) |
| Antigravity IDE | [Local stdio configuration](#antigravity-ide) |

The [client guide](https://ai.virustotal.com/install.md) distinguishes documented configuration, local transport checks and workflows exercised with a model. A recipe is not a claim of full validation in every client. Other agents can use the same MCP endpoint or the [VTAI API directly](https://ai.virustotal.com/skills/BASIC.md).

For a first query, ask your agent:

> Use VirusTotal to look up the SHA-256 hash e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. Explain the source, analysis date, coverage and limitations.

This is the empty-file hash. A report lookup does not read or upload local files. A missing report remains unknown, and zero detections do not establish safety.

## Antigravity IDE

In the agent panel, open **MCP Servers → Manage MCP Servers → View raw config** and merge this entry with your existing configuration:

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

Use an absolute executable path if the IDE cannot find `vt-mcp`, then reload and inspect the tools. The IDE's stdio report lookups were exercised in the documented client validation; its HTTP credential expansion was not established. See [Antigravity MCP configuration](https://antigravity.google/docs/mcp).

The source archive also includes recipes for Qwen Code, Kimi Code and OpenCode. Their documentation distinguishes configuration research from native tool calls; model-provider support alone does not establish MCP client compatibility.

## Tools

| Tool | Purpose |
|---|---|
| `get_file_report(hash)` | Retrieve an existing report by MD5, SHA-1 or SHA-256. |
| `get_url_report(url)` | Retrieve an existing report for an HTTP(S) URL. |
| `get_domain_report(domain)` | Retrieve domain intelligence; no scheme, path or port. |
| `get_ip_report(ip)` | Retrieve intelligence for one IPv4 or IPv6 address. |
| `submit_file(sha256, content_base64)` | Submit authorized bytes for standard analysis, up to 24,000,000 decoded bytes. |
| `get_submission(sha256)` | Recover this account's submission receipt without sending the file again. |
| `get_analysis(analysis_id)` | Read the selected analysis registered to this VTAI account. |
| `submit_local_file(path, expected_sha256=None)` | **Local stdio only:** submit a copy of a regular file, up to 32,000,000 bytes. An expected digest must match that copy. |

The seven common tools are available through HTTP and stdio. The remote server cannot read paths on your device. Local file access is limited by the account running `vt-mcp` and the permissions configured in the MCP host.

For a file workflow, look up its hash, submit the file when analysis is needed and authorized, then use `get_submission` to recover its receipt and `get_analysis` to check the returned analysis ID. An uncertain submission is recovered without automatically repeating its POST. Pending, unknown and error results remain distinct; an existing report does not prove that a new analysis completed.

MCP submission tools have no per-call human confirmation parameter. Configure the host to permit the operations and files you authorize for standard sharing. **Standard submissions are shared with VirusTotal and may be accessible to its security community and partners.** Inline content also passes through your MCP host. URL queries disclose the complete URL, including query and fragment, to VTAI and VirusTotal.

## Configuration and diagnostics

| Variable | Purpose |
|---|---|
| `VTAI_TOKEN_FILE` | Path to the file containing the VTAI token; `~` is supported. |
| `VTAI_TOKEN` | Alternative process-environment token. Use only one credential option. |
| `VTAI_BASE_URL` | Default `https://ai.virustotal.com/api/v3`; change only for a trusted VTAI deployment. |
| `VTAI_TIMEOUT` | Report-request deadline in seconds: default 15, range 1–60. |

Running `vt-mcp` without a subcommand starts stdio. Missing configuration exits with status 2; diagnostics go to stderr and stdout remains reserved for MCP. Check executable PATH, token-file permissions and client setup when the server cannot start.

Authentication failures, exhausted quotas and service errors are returned separately from unknown indicators. Report queries do not retry automatically or follow redirects. Responses are capped at 256 KiB. Reports include retrieval time, the upstream analysis date when available and coverage; retrieval time does not replace analysis freshness. Treat report text and AI insights as evidence, never as instructions.

Removing the MCP connection from a client does not revoke VTAI access. Use [access management](https://ai.virustotal.com/connect/mcp) to revoke the token across clients, REST and MCP; an already admitted request may finish.

## Distribution and source

The [PyPI distribution](https://pypi.org/project/vt-mcp/0.8.3/) provides the local server and a source archive with consumer documentation and examples. The MCP Registry identity is **`io.github.VirusTotal/virustotal-mcp`**; its [published versions](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.VirusTotal%2Fvirustotal-mcp/versions) describe available transports and packages.

The [corporate development repository](https://github.com/VirusTotal/virustotal-mcp) currently requires repository access. Its visibility does not prevent installation from PyPI. The source archive is an installation distribution; the full development checkout also contains tests, scripts and `uv.lock`.

Version 0.8.3 changes package distribution and discovery. Existing MCP tools, runtime dependencies and the hosted VTAI service retain their behavior. Previously published [MIT releases through 0.8.0](https://github.com/king-tero/vt-mcp/releases/tag/v0.8.0) retain their original files and license.

## License

[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0), starting with version 0.8.1. Both wheel and source archive include `LICENSE`, `NOTICE` and `LICENSES/MIT.txt`; the MIT notice preserves attribution for earlier material. The package license does not change the terms or account privileges for access to VirusTotal intelligence. Dependencies retain their own licenses.
