Metadata-Version: 2.4
Name: mcp-server-vdb
Version: 6.7.0
Summary: AppThreat Vulnerability Database MCP server
Author-email: Team AppThreat <cloud@appthreat.com>
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: Free Threading :: 1 - Unstable
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: appthreat-vulnerability-db[oras]==6.7.0
Requires-Dist: mcp[cli]>=1.22.0
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: bandit; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"

# 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](https://modelcontextprotocol.io/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](https://docs.astral.sh/uv/getting-started/installation/)

## 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:

```json
{
  "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.

```json
{
  "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)

```shell
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`

```json
{
  "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](../../README.md#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.vdb6`, `data.index.vdb6`, and `vdb.meta`. Set this explicitly for Docker volume mounts and local Claude Desktop configurations. |
| `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/vdbxz-app:v6.7.x` | OCI image URL used by MCP automatic downloads. Override this for internally published app-only artifacts. |
| `VDB_SQLITE_IMMUTABLE` | unset | Open existing `.vdb6` 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, 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 context](./docs/claude-context.png)

### Claude permissions on first run

![Claude permissions](./docs/claude-permissions.png)

### Claude results

![Vulnerability description](./docs/vuln-description.png)

### Latest malware

![Latest Malware](./docs/latest-malware.png)

## 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"

![MCP Inspector](./docs/vdb-mcp-inspector.png)

### 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:

```json
{
  "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
}
```
