alephnan/MCP-VirusTotal

MCP VirusTotal Server

This project implements a Model Context Protocol (MCP) server that exposes a curated toolkit for querying VirusTotal. The service offers lookups for hashes, URLs, IPs, and domains plus optional submission flows. It is designed for safe use by LLM agents that need deterministic, reproducible access to VirusTotal data.

Features

• Strictly typed tool definitions for common VirusTotal lookups.
• Pydantic-based validation and normalization of inputs.
• Tenacity-powered retries with jitter and respect for VirusTotal rate limits.
• Pluggable caching layer (in-memory or Redis) to avoid redundant requests.
• Structured JSON logging with correlation IDs and redaction of secrets.
• Dockerized deployment with optional Redis sidecar and GitHub Actions CI.

MCP Tools

Each tool enforces strict validation and returns compact JSON responses suitable for downstream LLM consumption.

Configuration

All settings are environment-driven; refer to .env.example for defaults. Key options include:

• VT_API_KEY – required VirusTotal API key.
• ALLOW_FILE_SUBMISSION – toggle file upload support (default false).
• CACHE_BACKEND – memory or redis.
• CACHE_TTL_SECONDS – cache freshness window; set 0 to disable caching.
• MAX_FILE_SIZE_MB – safety limit for file submissions.

The server loads variables from a local .env file when present and can be safely configured via Docker/Compose secrets.

Getting Started

1. Create a Python virtual environment and install dependencies:

   python -m venv .venv
   source .venv/bin/activate
   pip install -U pip
   pip install -e .[dev]
   

2. Provide configuration via environment variables or a .env file. See .env.example for required values.

3. Launch the MCP server:

   VT_API_KEY=... python -m mcp_vt.server
   

   The server communicates via MCP's stdio transport and exposes the tools listed above.

Running Tests

• Unit tests (mocked VirusTotal):

  pytest -m unit
  

• Integration tests (real VirusTotal, requires VT_API_KEY):

  VT_API_KEY=... pytest -m integration
  

Integration tests are automatically skipped when no API key is available.

Claude Configuration

Add the server to your Claude MCP config.json (usually at ~/.config/claude/config.json). Example entry:

{
  "mcpServers": [
    {
      "name": "virustotal",
      "command": "python",
      "args": ["-m", "mcp_vt.server"],
      "env": {
        "VT_API_KEY": "${VT_API_KEY}"
      }
    }
  ]
}

Replace ${VT_API_KEY} with a secure reference (env var, secret manager, etc.). Restart Claude after updating the configuration so the new server is detected.

Docker Usage

Build and run the container locally with Docker Compose:

docker compose up --build

The compose stack provisions the MCP server alongside an optional Redis cache (listening on an internal network). The server container runs as an unprivileged user with a read-only filesystem and ephemeral /tmp.

Run without Redis

If you prefer the in-memory cache only, build and run the image directly without starting Redis:

docker build -t mcp-vt-memory .
docker build -t mcp-vt-memory . && docker run --rm --env-file .env -e CACHE_BACKEND=memory mcp-vt-memory

The server still communicates over stdio, so keep the container attached (no daemon mode) while an MCP client is connected.

Continuous Integration

GitHub Actions workflow .github/workflows/ci.yml installs the project, runs the unit suite for Python 3.11 and 3.12, and conditionally executes integration tests when the VT_API_KEY secret is present.

Licensing

Released under the .