vulnerability-db

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:

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:

Pre-requisites

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:

{
  "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:

Variable Default Description
VDB_HOME Platform user data directory for vdb Directory containing data.vdb7, data.index.vdb7, and vdb.meta. Set this explicitly for Docker volume mounts and local Claude Desktop configurations.
VDB_SHARDS_DIR $VDB_HOME/shards Type-shard store directory. Searches fan out across shards when the main DB under VDB_HOME is a shard (vdb.meta completeness: "partial").
VDB_AGE_DAYS 2 Number of days before the server treats the local database as stale. When stale or missing and ORAS support is installed, the server downloads the app-only database on startup. Use an integer string.
VDB_APP_ONLY_DATABASE_URL ghcr.io/appthreat/vdb7-app-only:v7.0.x-xz OCI image URL used by MCP automatic downloads. Override this for internally published app-only artifacts. Prefer the -xz suffix: it unpacks unconditionally, while -zst needs a zstd decompressor (Python 3.14+ or a zstd binary on PATH).
VDB_SQLITE_IMMUTABLE unset Open existing .vdb7 files with SQLite’s immutable URI option in read-only deployments.

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 context

Claude permissions on first run

Claude permissions

Claude results

Vulnerability description

Latest malware

Latest Malware

Configuration for MCP Inspector

Click “Connect”

MCP Inspector

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
}
This site is open source. Improve this page.