Introduction

This folder contains the source code for running VDB as a Model Context Protocol (MCP) server. Below you can find the configuration for running the VDB MCP server with Claude Desktop. Please feel free to share the configuration for other clients via pull requests.

What is available

The MCP server provides:

• Structured JSON tool results with summaries and machine-readable evidence.
• Bulk search tools for package lists and CycloneDX BOMs.
• Filter-aware search for severity thresholds, sources (osv, nvd, github, aqua), date ranges, malware-only / exclude-malware, package scope (app_only, os_only), package ecosystem, and pagination.
• Metadata and full-text search over aliases, references, package names, descriptions, and affected functions/modules.
• Resource templates such as cve://{id} and purl://{purl}.
• Concrete resources such as vdb://metadata, vdb://health, vdb://sources, and vdb://malware/latest.
• A db_refresh tool that fetches or refreshes local data through the same staged, validated, atomically-swapped path as vdb db refresh — {"target": "full"} (optionally app_only or an image URL override), {"target": "shards", "shards": ["npm", "pypi"]}, or {"target": "sync"} (the default: refresh everything already local). Every result carries the post-refresh health report.
• Richer prompts for package-risk assessment, CVE triage, SBOM summaries, fix prioritization, version-match explanations, and overlay review.

VDB 7 shard stores, coverage, and health

VDB 7 data can be a full database under VDB_HOME or a set of type shards (see the root README type-shard section). The server is honest about which one it has:

• Every tool payload carries a status: ok, coverage_gap (some requested purl types have no local shard — those results were NOT checked), or stale_data (a shard lags its siblings by more than shard_store.STALE_SHARD_LAG_DAYS days). Shard-mode payloads also carry a coverage object with uncovered_types, shard_build_ids, and stale_shards; batch and BOM results mark affected packages with a per-package coverage_gap flag.
• An empty or unusable database is a tool error, never an empty result list that reads as "no vulnerabilities found".
• vdb://health reports status (ok | degraded | error | empty), the main-DB state, and the full per-shard store report (build ids, ages, staleness, missing group shards) — the same computation vdb db status uses. Use it to tell "I have no deb data" from "my deb data is three weeks old" from "I am fully current".
• When the database is missing or older than VDB_AGE_DAYS at startup, the server refreshes it with db_refresh target=full --app-only semantics (downloaded to a staging directory, validated as a usable v7 artifact, then atomically swapped in — a failed or interrupted download never damages the existing database). A failed refresh is a visible warning and the server continues with whatever local data it has.

Pre-requisites

• Python >= 3.10 installed
• docker or Rancher Desktop (or)
• uv installed

docker-based execution (Recommended)

Use our container image ghcr.io/appthreat/mcp-server-vdb:master.

Claude Desktop configuration

Edit the file using VS code or any editor of your choice. ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, the config file is $env:AppData\Claude\claude_desktop_config.json. Use the below configuration:

{
  "mcpServers": {
    "vdb": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "VDB_HOME=/db",
        "-v",
        "$HOME/vdb:/db:rw",
        "ghcr.io/appthreat/mcp-server-vdb:master"
      ]
    }
  }
}

nerdctl example.

{
  "mcpServers": {
    "vdb": {
      "command": "nerdctl",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "VDB_HOME=/db",
        "-v",
        "$HOME/vdb:/db:rw",
        "ghcr.io/appthreat/mcp-server-vdb:master"
      ]
    }
  }
}

Restart the Claude Desktop application.

If you get ENOENT error, specify the full path to docker. On a mac, /Applications/Docker.app/Contents/Resources/bin/docker.

Local uv-based execution (Developers only)

git clone https://github.com/AppThreat/vulnerability-db.git
cd vulnerability-db
python -m pip install .

export VDB_HOME=$HOME/vdb
mkdir -p $VDB_HOME
vdb db refresh full --app-only
uv --directory packages/mcp-server-vdb run mcp-server-vdb

Claude Desktop configuration

Edit the file using VS code or any editor of your choice. ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, the config file is $env:AppData\Claude\claude_desktop_config.json.

Use the below configuration and adjust the following paths:

• absolute path to the mcp-server-vdb package inside the packages directory.
• VDB_HOME - Full path to the directory containing the vulnerability database. Must have run vdb db refresh full --app-only

{
  "mcpServers": {
    "vdb": {
      "command": "uv",
      "args": [
        "--directory",
        "/Volumes/Work/AppThreat/vulnerability-db/packages/mcp-server-vdb",
        "run",
        "mcp-server-vdb"
      ],
      "env": {
        "VDB_HOME": "/Users/guest/vdb"
      }
    }
  }
}

Restart the Claude Desktop application.

Environment variables

The MCP server uses the same vdb configuration as the CLI. See the root README environment variables for the full reference. The most common MCP settings are:

If the MCP server needs extended metadata searches such as full-text, alias, reference, package-name, or symbol lookup, v7 publishes no pre-built extended artifacts — pre-populate VDB_HOME with a database built using vdb --cache --include-metadata (or --cache-os --include-metadata), or point VDB_DATABASE_URL/VDB_APP_ONLY_DATABASE_URL at your own internally published metadata artifact.

Screenshots

Claude context screen

Claude permissions on first run

Claude results

Latest malware

Configuration for MCP Inspector

• Transport Type: STDIO
• Command: uv
• Arguments: --directory /absolute/path/to/vulnerability-db/packages/mcp-server-vdb run mcp-server-vdb

Click "Connect"

Testing

1. Click "List Tools". You should see structured tools such as search_by_purl_like, search_full_text, search_packages, search_bom_summary, and search_bom_detailed.
2. Select search_by_purl_like and enter a purl string such as pkg:swift/vapor/vapor@4.89.0.
3. Confirm that the tool returns structured JSON content with summary and results.
4. Try resources such as vdb://metadata, vdb://health, or cve://CVE-2024-25169.

Example common search options

Many tools accept the following optional fields in addition to their main locator:

{
  "severity_threshold": "HIGH",
  "source": ["osv", "github"],
  "exclude_malware": true,
  "package_ecosystem": "pypi",
  "with_data": true,
  "summary_only": false,
  "include_references": true,
  "include_affected_symbols": true,
  "include_remediation": true,
  "include_evidence": true,
  "page": 1,
  "page_size": 25
}