Osv Advisory MCP Server

What osv-advisory-mcp-server does

osv-advisory-mcp-server exposes OSV.dev vulnerability data through MCP tools. It can check an exact package version by ecosystem and name, accept a Package URL (PURL), scan a dependency list or SBOM, inspect a full Git commit hash, retrieve an advisory by ID, and list the ecosystem identifiers accepted by OSV.dev.

The package and commit queries return advisory information such as aliases, severity data, affected ranges, and fixes where applicable. Full advisory lookups include the record details, affected packages, version ranges, fixes, weaknesses, and references. OSV.dev is public and does not require an API key.

How it works

The server supports both stdio and Streamable HTTP transports. A local MCP client can launch it with the npm package, while HTTP clients can connect to the hosted endpoint or to a locally configured HTTP listener.

osv_query_package accepts either name, an exact, case-sensitive ecosystem, and version, or a PURL containing a version. Versions are exact rather than ranges. osv_query_batch accepts between one and 1,000 package entries, allows the two input forms to be mixed, and preserves the input index for each result. It fetches unique advisory records so batch rows can include full advisory data rather than only matching IDs.

Commit lookups require a complete 40-character SHA-1 or 64-character SHA-256 hash. Advisory IDs are matched case-sensitively and may use identifiers such as GHSA, CVE, PYSEC, or RUSTSEC. Ecosystem names are also case-sensitive; the ecosystem-list tool returns the accepted strings.

Setup and configuration

Run locally through npm with an MCP client command such as npx -y @cyanheads/osv-advisory-mcp-server. The public hosted MCP endpoint is https://osv-advisory.caseyjhand.com/mcp. A Docker deployment and source build are also supported.

All configuration variables are optional. OSV request timeouts, batch request concurrency, and the maximum number of followed result pages can be adjusted with OSV_REQUEST_TIMEOUT_MS, OSV_BATCH_CONCURRENCY, and OSV_QUERY_MAX_PAGES. Transport and HTTP behavior are controlled with MCP_TRANSPORT_TYPE, MCP_HTTP_PORT, MCP_HTTP_ENDPOINT_PATH, MCP_PUBLIC_URL, and MCP_SESSION_MODE. MCP_AUTH_MODE selects none, jwt, or oauth for HTTP deployments.

Tools and capabilities

• osv_query_package: Check one exact package version by name and ecosystem or by PURL.
• osv_query_batch: Audit up to 1,000 package versions in a dependency list or SBOM.
• osv_query_commit: Find advisories associated with a complete Git commit hash.
• osv_get_vulnerability: Retrieve one complete OSV advisory record by exact ID.
• osv_list_ecosystems: Return the supported, case-sensitive ecosystem strings.

Batch scans report vulnerable, clean, truncated, and error counts, along with the worst severity and affected row indexes. Individual rows can contain errors without failing the entire batch call.

Limitations and notes

Queries are subject to the configured request timeout, page limit, and batch concurrency. A truncated result means additional OSV pages were not followed; an empty truncated result is not confirmation that the package or commit is clean. Batch scans have a 50-second deadline, and truncated rows are excluded from the clean count.

Responses are capped at 24,000 bytes. Overflow pages and deferred entries must be retrieved using the pagination information returned by the tool. Advisory text in rendered content escapes HTML and unsafe link constructs, while structured content preserves OSV strings. Commit results provide Git ranges and repository URLs but do not infer package-specific fixed versions.