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.
• Richer prompts for package-risk assessment, CVE triage, SBOM summaries, fix prioritization, version-match explanations, and overlay review.

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 --download-image
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 --download-image

{
  "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, point VDB_APP_ONLY_DATABASE_URL at an app-only extended artifact such as ghcr.io/appthreat/vdbxz-app-extended:v6.7.x, use your own mirrored extended image, or pre-populate VDB_HOME with a database built using vdb --cache --include-metadata.

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
}