osv-advisory-mcp-server

---

Overview

Vulnerability data from OSV.dev, the open-source vulnerability database. Query a package version or Git commit, batch-audit a dependency list or SBOM, and fetch complete advisory records with CVSS severity, CVE aliases, and affected version ranges.

Tools

Tool	Description
osv_query_package	Query a package version by name/ecosystem/version or Package URL (PURL)
osv_query_batch	Audit up to 1000 package versions in one call — a full dependency list or SBOM
osv_query_commit	Query known vulnerabilities for a full Git commit hash
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

• Provide name, ecosystem (case-sensitive exact match), and version, or a purl such as pkg:pypi/[email protected]. A PURL needs exactly one version: embedded in the URL or supplied separately. Versions are exact, never ranges
• Each advisory carries CVE aliases, severityLabel with its severitySource, the queried package's fixedVersions, affectedRanges, and cweIds
• truncated: true means OSV had more pages than OSV_QUERY_MAX_PAGES follows, so an empty vulns list is not a clean result; an unrecognized ecosystem fails as invalid_ecosystem

---

osv_query_batch _tool

• 1–1000 {name, ecosystem, version} tuples or {purl, version?} entries per call; mix either form, and results[i] matches packages[i]
• Each row carries vulnerable, vulnCount, vulns, truncated, and error; a failure lands in the affected rows' error instead of failing the call
• summary totals the scan (vulnerableCount, cleanCount, truncatedCount, errorCount, totalVulns, worstSeverity), and truncated rows never count as clean. The whole scan has a 50-second deadline

---

osv_query_commit _tool

• One full commit: 40 hexadecimal characters for SHA-1 or 64 for SHA-256; either letter case is accepted, abbreviations are rejected
• Advisories retain record-wide severity, aliases, and GIT ranges with repository URLs and ordered events. No package-specific fixedVersions are inferred
• truncated: true means more OSV pages remain; an empty truncated result is not confirmed clean

---

osv_get_vulnerability _tool

• One exact advisory ID from any OSV source (GHSA-, PYSEC-, RUSTSEC-, GO-, DSA-, USN-, CVE-, …), matched case-sensitively
• Full record: details, aliases, every affected package with its ranges and fixes, severityLabel, cweIds, and references
• An unknown ID fails as vulnerability_not_found; withdrawn is set only on retracted advisories

---

osv_list_ecosystems _tool

• No input; returns the ecosystems strings the query tools accept, plus a note with the date the list was last checked against OSV.dev
• Strings are case-sensitive exact matches: PyPI works, pypi fails

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 public and keyless, with no published rate limit
• osv_query_batch finds matching advisory IDs through OSV's /v1/querybatch, then fetches each unique advisory once, so batch rows carry the full records (aliases included) the batch endpoint omits; requests are capped by OSV_BATCH_CONCURRENCY
• osv_list_ecosystems is checked against the live OSV schema and API with bun run check:ecosystems

Agent-friendly output:

• Truncation is never read as clean — truncated flags incomplete OSV pagination, and truncated batch rows are left out of cleanCount
• aliases (CVE IDs) on every advisory chain to nist-nvd-mcp-server for CVSS base scores and CISA KEV status
• Responses are capped at 24,000 bytes. Start retrieval by repeating the original input with page: overflow.page. Continue the same path with offset: page.nextOffset and revision: page.revision until nextOffset is null. Fetch each entries[].deferred.path separately at offset zero without a revision; never copy the whole output page object into the input
• Advisory text in content[] is escaped so it can't render as live HTML or links; 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.

{
  "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, and every variable is optional.

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 followed per package or commit before a result is marked 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: stateless, stateful, or auto.	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
LOG_TOOL_FAILURE_PAYLOADS	Log each failed tool call's arguments and result, redacted by key name and capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (default 16384). A secret inside a free-form value is not redacted.	false
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
  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

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_query_commit, 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.