osv-advisory-mcp-server

Public Hosted Server: https://osv-advisory.caseyjhand.com/mcp

Overview

Vulnerability data from OSV.dev, the open-source vulnerability database. Query a single package version, batch-audit a full dependency list or SBOM, and fetch complete advisory records with CVSS severity, CVE aliases, and affected version ranges. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Related MCP server: dep-guard-mcp

Capability reference

osv_query_package tool

• Accepts name, ecosystem (case-sensitive exact match), and version — an exact version string, not a range

• Surrounding whitespace is trimmed from all three before the request, and queryMeta echoes the trimmed values; interior whitespace (Rocky Linux) is kept. Blank or whitespace-only values are rejected before any upstream call

• Returns matching advisories with OSV IDs, CVE aliases, severity entries (CVSS vectors, Ubuntu priorities), severityLabel with its severitySource, fixedVersions, affectedRanges (SEMVER/ECOSYSTEM/GIT), and cweIds

• fixedVersions lists every fix the advisory records for the queried package (one per affected interval), matched the way OSV matches the query — release-suffixed ecosystems (Debian → Debian:12, Ubuntu:22.04 → Ubuntu:22.04:LTS) and PEP 503 names on PyPI. Other packages' fixes and GIT commits stay out of it; affectedRanges keeps every range

• truncated: true means OSV paginated beyond OSV_QUERY_MAX_PAGES (default 10) — an empty vulns array with truncated: true is NOT a confirmed clean result

• Typed invalid_ecosystem error when the ecosystem string isn't recognized by OSV — call osv_list_ecosystems for valid values, then retry

• aliases on each vuln chain to nist-nvd-mcp-server for CVSS base scores, EPSS exploitation probability, and CISA KEV status

osv_query_batch tool

• Accepts an array of {name, ecosystem, version} tuples, 1–1000 per call; results[i] corresponds positionally to packages[i]

• Each row's fields are trimmed of surrounding whitespace the same way as osv_query_package, and results[i] echoes the trimmed values; a blank field in any row rejects the call

• Per-package vulnerable, vulnCount, vulns (with aliases, severityLabel, and the row package's fixedVersions), and a nullable error — one bad ecosystem or upstream failure fails only that row, not the whole batch

• Aggregate summary: totalPackages, vulnerableCount, cleanCount, truncatedCount, errorCount, totalVulns, worstSeverity

• cleanCount excludes truncated rows — a per-package truncated: true result is never counted clean even with zero findings

• Per-package requests run in parallel, capped by OSV_BATCH_CONCURRENCY (default 10)

osv_get_vulnerability tool

• Accepts one exact, complete advisory ID from any OSV source database, matched case-sensitively — GHSA- (GitHub), PYSEC- (PyPI), RUSTSEC- (Rust), GO- (Go), DSA-/DLA- (Debian), USN- (Ubuntu), RHSA- (Red Hat), CVE-, and the rest. IDs come from osv_query_package / osv_query_batch results

• Surrounding whitespace is trimmed before the request (" GHSA-29mw-wpgm-hmr9 " resolves); input that can't be an OSV ID (wildcards, a bare package name, a prefix with no ID) is rejected before any upstream call, with a message naming the expected form

• Returns the full record — details text, all CVE aliases, every affected package with its version ranges, ordered fixed events, and any package-level severity, severity entries with severityLabel and severitySource, cweIds, and references (ADVISORY, FIX, REPORT, etc.)

• Typed vulnerability_not_found error when the ID doesn't exist in OSV — the recovery covers case and the Debian/Ubuntu/SUSE revision suffix (DSA-5678-1, not DSA-5678); a CVE-style alias may still resolve via nist-nvd-mcp-server

• withdrawn is present only on retracted advisories — treat as no longer active, not as an error

osv_list_ecosystems tool

• No input; returns the static list of valid ecosystem identifier strings plus an advisory note on currency

• Ecosystem strings are case-sensitive exact matches — "pypi" fails where "PyPI" succeeds

• Every ecosystem in the OSV schema's ecosystemName enum that OSV.dev accepts at query time, plus GIT (accepted via the ecosystemWithSuffix pattern); a schema ecosystem OSV.dev still rejects is left out. The note carries the verification date; the list may lag later additions

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

OSV-specific:

• No API key required — OSV.dev is fully public, keyless, and has no published rate limit

• osv_query_batch issues parallel per-package requests (capped by OSV_BATCH_CONCURRENCY) and returns full records, including aliases, that the upstream OSV batch endpoint omits

• Per-package failures are isolated in osv_query_batch — one invalid ecosystem or upstream error surfaces as that row's error without failing the whole batch

• Ecosystem discovery via osv_list_ecosystems — the OSV schema's ecosystems that OSV.dev accepts, checked against both with bun run check:ecosystems

Agent-friendly output:

• aliases (CVE IDs) surfaced on every vuln entry — the composition point for chaining to nist-nvd-mcp-server for CVSS base scores, EPSS, and CISA KEV status

• severityLabel from the first source that yields one: database_specific.severity (GHSA, openEuler, and others; Medium reads as MODERATE), an Ubuntu priority, then the highest CVSS v3/v4 score computed from the vector as published (every metric group of a CVSS 4.0 vector; base and temporal for CVSS 3.x). Package-level severity counts when the record has none. severitySource names the entry used, with the computed score for CVSS; both are null rather than fabricated when no source yields a label

• Truncation is never silently treated as clean — truncated (single query) and per-package truncated plus truncatedCount (batch) flag incomplete OSV pagination, and truncated rows are excluded from cleanCount

• Query echo (queryMeta / effectiveQuery) and aggregate batch summary (worstSeverity, vulnerableCount, cleanCount) let agents verify requests and triage without reading every row

• Advisory text is framed as untrusted data in content[] and escaped at the render boundary: tag-shaped text (<template>, <script), autolinks, reference definitions, non-http(s) link destinations (javascript:), and forged frame tags can't turn into live HTML or links in a Markdown client. structuredContent keeps every OSV string verbatim

Getting started

Public Hosted Instance

A public instance is available at https://osv-advisory.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "osv-advisory-mcp-server": {
      "type": "streamable-http",
      "url": "https://osv-advisory.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file. No API key is required — OSV.dev is fully public.

{
  "mcpServers": {
    "osv-advisory-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/osv-advisory-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "osv-advisory-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/osv-advisory-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "osv-advisory-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/osv-advisory-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).

• No API key required — OSV.dev is fully public.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/osv-advisory-mcp-server.git

2. Navigate into the directory:

cd osv-advisory-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env if needed (no required vars)

Configuration

All configuration is validated at startup. No server-specific env vars are required — OSV.dev is keyless and fully public.

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  bun run check:ecosystems  # Compare osv_list_ecosystems with the live OSV schema and API

Docker

docker build -t osv-advisory-mcp-server .
docker run --rm -p 3010:3010 osv-advisory-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/osv-advisory-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for request-scoped logging, ctx.enrich for response context, and ctx.signal for cancellable OSV requests

• Register new tools via the barrel in src/mcp-server/tools/definitions/index.ts

• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.