io.github.cyanheads/osv-advisory-mcp-server

---

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

Tool	Description
osv_query_package	Query known vulnerabilities for a single package version by name, ecosystem, and version
osv_query_batch	Batch vulnerability query for an array of package tuples — one call for a full dependency list or SBOM audit
osv_get_vulnerability	Fetch the full advisory record for a single OSV vulnerability ID
osv_list_ecosystems	Return the list of supported ecosystem identifier strings

Capability reference

osv_query_package _tool

• Accepts name, ecosystem (case-sensitive exact match), and version — an exact version string, not a range
• Returns matching advisories with OSV IDs, CVE aliases, CVSS severity vectors, severityLabel, fixedVersions, affectedRanges (SEMVER/ECOSYSTEM/GIT), and cweIds
• 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]
• Per-package vulnerable, vulnCount, vulns (with aliases and severityLabel), 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 any OSV ID prefix: GHSA- (GitHub), PYSEC- (Python), RUSTSEC- (Rust), GO- (Go), DSA-/DLA- (Debian), CVE- (direct fallback lookups)
• Returns the full record — details text, all CVE aliases, every affected package and version range, fixedVersions, CVSS severity vectors, cweIds, and references (ADVISORY, FIX, REPORT, etc.)
• Typed vulnerability_not_found error when the ID doesn't exist in OSV — 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
• Sourced from the OSV schema's ecosystemName enum plus GIT (accepted via the ecosystemWithSuffix pattern); may lag newly added ecosystems

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 validation via osv_list_ecosystems, kept in sync with the OSV schema's ecosystemName enum

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 derived from GHSA database_specific.severity or the highest CVSS base score; null rather than fabricated when neither source is available
• 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

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.

Variable	Description	Default
OSV_REQUEST_TIMEOUT_MS	HTTP request timeout for OSV.dev API calls, in milliseconds.	10000
OSV_BATCH_CONCURRENCY	Maximum concurrent OSV.dev requests issued by osv_query_batch.	10
OSV_QUERY_MAX_PAGES	Maximum OSV.dev result pages osv_query_package follows before marking a result truncated.	10
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	Port for HTTP server.	3010
MCP_HTTP_ENDPOINT_PATH	HTTP endpoint path.	/mcp
MCP_PUBLIC_URL	Public origin override for TLS-terminating reverse-proxy deployments.	none
MCP_SESSION_MODE	HTTP session mode: stateful, stateless, or auto. createApp() declares stateless — no tool has a multi-round input flow — and setting this overrides it.	stateless
MCP_AUTH_MODE	Auth mode: none, jwt, or oauth.	none
MCP_LOG_LEVEL	Log level (RFC 5424).	info
LOGS_DIR	Directory for log files (Node.js only).	<project-root>/logs
STORAGE_PROVIDER_TYPE	Storage backend.	in-memory
OTEL_ENABLED	Enable OpenTelemetry instrumentation (spans, metrics, completion logs).	false

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
  

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

Directory	Purpose
src/index.ts	createApp() entry point — registers tools and inits services.
src/config	Server-specific environment variable parsing and validation with Zod.
src/mcp-server/tools	Tool definitions (*.tool.ts) — osv_query_package, osv_query_batch, osv_get_vulnerability, osv_list_ecosystems.
src/services/osv-api	OSV.dev REST API service — fetch, retry, response normalization.
tests/	Unit and integration tests mirroring src/.

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.