Osv Advisory Mcp Server

io.github.cyanheads由 GitHub 帳號 cyanheads 發布v0.6.0更新於 Nov 21, 2026

Query OSV.dev for package vulnerabilities and batch-audit dependency lists via MCP.

已驗證Streamable HTTP可網頁執行開發者工具安全與監控

概覽

AI 產生的概覽

以唯讀、免金鑰方式存取 OSV.dev,讓助理查詢套件版本、Git 提交及整份相依清單的已知漏洞。

可以做什麼
  • 列出查詢工具支援的生態系識別字及其標準拼寫。
  • 依名稱/生態系/版本或套件 URL 查詢單一確切版本的已知漏洞。
  • 批次稽核最多 5000 筆相依清單或 SBOM,回傳逐列結果與掃描彙總。
  • 依完整 Git 提交雜湊查詢相關公告。
  • 依 OSV 編號取得完整公告記錄,含別名、受影響範圍、修正版本、CVSS 嚴重度與參考連結。
適用情境
適合稽核相依套件、排查 lockfile 或 SBOM,或確認某個套件版本、某次提交是否有已知漏洞,並直接在助理內查看完整公告內容。
執行需求
可作為公開託管的 HTTP 端點使用,也可透過 npx(Node.js)或 Docker 在本機執行。不需 API 金鑰或帳號,OSV.dev 為公開服務。所有設定變數皆為選用,涵蓋傳輸方式、HTTP 主機/連接埠/路徑、驗證模式、逾時、批次並行與分頁上限。
安裝前請注意
唯讀且免金鑰,不會索取憑證。結果可能不完整:truncated 標記、列層級錯誤與未解析的來源套件對應都代表掃描未必乾淨,批次呼叫只處理最多 5000 筆中的前 1000 筆。查詢內容與套件識別字會傳送至 OSV.dev。選用的失敗酬載記錄會寫下工具參數,自由文字中的密鑰不會被遮蔽。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Osv Advisory Mcp Server,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Web executable,透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

交給代理程式安裝

把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式,或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南,先向你展示發布者、端點和登入方式,經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。

閱讀 https://sourceweft.com/mcp/io.github.cyanheads%2Fosv-advisory-mcp-server/install.md,並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前,先告訴我它的發布者、端點和登入方式,等我確認。不要把 API 金鑰寫進命令或我會提交的檔案;問我金鑰應從哪裡取得。

檢視代理程式所依據的安裝指南

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

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

README

@cyanheads/osv-advisory-mcp-server

Query OSV.dev for package vulnerabilities, batch-audit dependency lists, and fetch full advisory records via MCP. STDIO or Streamable HTTP.

5 Tools · 1 Skill


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

ToolDescription
osv_query_packageQuery a package version by name/ecosystem/version or Package URL (PURL)
osv_query_batchAudit the first 1,000 package versions in a submission of up to 5,000
osv_query_commitQuery known vulnerabilities for a full Git commit hash
osv_get_vulnerabilityFetch the full advisory record for a single OSV vulnerability ID
osv_list_ecosystemsReturn the list of supported ecosystem identifier strings

Capability reference

osv_query_package tool

  • Provide name, ecosystem, and version, or a purl such as pkg:pypi/[email protected]. Known ecosystem bases normalize case (pypi → PyPI); release and repository suffixes retain their spelling. A PURL needs exactly one version: embedded in the URL or supplied separately. Versions are exact, never ranges
  • Alpine needs a release branch, such as Alpine:v3.17 or distro=alpine-3.17.3 in a PURL. Debian PURLs accept known releases or codenames, with an optional debian- prefix. Numeric Ubuntu PURL qualifiers such as distro=ubuntu-22.04.1 select the release Ubuntu:22.04
  • For a release-qualified Ubuntu query, supply the installed binary name and version. Both package tools look up the source packages OSV indexes for that release. For example, libssl3 on Ubuntu:22.04:LTS resolves to openssl. A fallback lookup covers only the supplied name and marks coverage incomplete. A mapping rate limit or exhausted deadline requires a retry
  • Maven needs groupId:artifactId (a single groupId/artifactId slash normalizes). Composer PURLs map to Packagist; an optional repository_url keeps repository scope
  • Unsupported ecosystem-specific constraints fail as invalid_version; npm/crates.io exact pins with = or == normalize to the installed version
  • Each advisory carries CVE aliases, optional upstream IDs, severityLabel with its severitySource, the queried package's fixedVersions, affectedRanges, and cweIds
  • truncated: true indicates more OSV pages remain. Pass nextCursor as cursor with the same identifier to continue. Repeat that input cursor alongside page when retrieving fields from a resumed reply. An empty initial result confirms no known vulnerabilities when lookup and source resolution completed. An empty terminal resume only confirms exhaustion of the continuation
  • When upgrading from before 0.6.0, restart any Ubuntu PURL query with a numeric distro qualifier by omitting its old cursor. The new query scopes findings to the requested release

osv_query_batch tool

  • Submit 1–5,000 {name, ecosystem, version} tuples or {purl, version?} entries. The call processes the first 1,000. Set OSV_BATCH_SERVE_OVER_CAP=false to reject submissions above 1,000
  • summary.submittedPackages, unprocessedCount, and nextInputOffset account for the input. If nextInputOffset is set, submit packages.slice(nextInputOffset) in a new call and add that offset to its row indices. All outcome counts describe the processed prefix
  • 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
  • vulnerableRows, errorRows, and truncatedRows in summary retain original zero-based indices even when the preview omits those rows. Lists can overlap; retrieve a row with /results/<index>
  • summary.sourceResolutionUnavailableRowRanges identifies rows checked under their supplied Ubuntu names after a mapping failure. For example, 0,3-5 means rows 0, 3, 4, and 5. Those rows are excluded from cleanCount
  • Resume a row through osv_query_package with its original identifier and nextCursor as cursor
  • If a nested advisory page returns a timeout or upstream error, retry the same path. You can also retrieve /results/<index>/error for the row diagnostic

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, upstream IDs, and GIT ranges with repository URLs and ordered events. Readable advisory sections retain complex values in fenced JSON. No package-specific fixedVersions are inferred
  • Pass nextCursor as cursor with the same commit to continue a truncated result. An empty terminal resume confirms the continuation is exhausted

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, optional upstream and related IDs, every affected package with its ranges and source metadata, severityLabel, cweIds, and references
  • When OSV publishes evidence for a converted range, inspect /affected/<index>/ranges/<index>/database_specific. Its source tags and release boundaries accompany OSV's normalized events
  • 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
  • Returns canonical spellings. Query tools normalize known base names case-insensitively and forward unknown names to OSV.dev; release and repository suffixes remain unchanged

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
  • CVE-shaped aliases and upstream IDs chain to nist-nvd-mcp-server for CVSS base scores and CISA KEV status. The lists remain separate; a distribution advisory can cover several upstream vulnerabilities
  • Response fields are bounded to 24,000 bytes; upstream cursors are returned intact outside that budget. 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[] escapes HTML and unsafe-link constructs while preserving HTTP(S) links; caller coordinates render literally. Commit data and affected metadata use reversible JSON where literal rendering needs it. structuredContent keeps every OSV string verbatim

Getting started

Use the public hosted instance with Claude Code:

sh
claude mcp add --transport http osv-advisory-mcp-server https://osv-advisory.caseyjhand.com/mcp

Or run locally through npm:

sh
claude mcp add osv-advisory-mcp-server -- npx -y @cyanheads/osv-advisory-mcp-server

For other MCP clients, add this to the client configuration:

json
{  "mcpServers": {    "osv-advisory-mcp-server": {      "command": "npx",      "args": ["-y", "@cyanheads/osv-advisory-mcp-server"]    }  }}

No API key is required. For Docker or a source build, see Running the server.

Configuration

All configuration is validated at startup, and every variable is optional.

VariableDescriptionDefault
OSV_REQUEST_TIMEOUT_MSTimeout per OSV.dev HTTP attempt, in milliseconds. Package, commit and batch queries share a 50-second per-operation deadline across requests, retries, response reads and hydration.40000
OSV_BATCH_CONCURRENCYMaximum concurrent OSV.dev requests issued by osv_query_batch.10
OSV_QUERY_MAX_PAGESMaximum OSV.dev result pages followed per package or commit before a result is marked truncated.10
OSV_BATCH_SERVE_OVER_CAPAccept up to 5,000 packages and process the first 1,000. Set false to restore the 1,000-entry submission ceiling.true
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTPort for HTTP server.3010
MCP_HTTP_ENDPOINT_PATHHTTP endpoint path./mcp
MCP_PUBLIC_URLPublic origin override for TLS-terminating reverse-proxy deployments.none
MCP_SESSION_MODEHTTP session mode: stateless, stateful, or auto.stateless
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (RFC 5424).info
LOGS_DIRDirectory for log files. Relative paths resolve from the server package root.<server-package-root>/logs
LOG_TOOL_FAILURE_PAYLOADSLog 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_TYPEStorage backend.in-memory
OTEL_ENABLEDEnable OpenTelemetry instrumentation (spans, metrics, completion logs).false

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

Running the server

Local development

Requires Bun v1.4.4 or higher (or Node.js v24+).

sh
git clone https://github.com/cyanheads/osv-advisory-mcp-server.gitcd osv-advisory-mcp-serverbun installcp .env.example .env
  • Build and run:

    sh
    # One-time buildbun run rebuild
    # Run the built serverbun run start:stdio# orbun run start:http
  • Run checks and tests:

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

Docker

sh
docker run --rm -p 3010:3010 ghcr.io/cyanheads/osv-advisory-mcp-server:latest

The image defaults to HTTP transport, stateless session mode, and logs to /var/log/osv-advisory-mcp-server. For stdio, use docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio ghcr.io/cyanheads/osv-advisory-mcp-server:latest. Build locally with docker build -t osv-advisory-mcp-server .; OpenTelemetry peers are installed by default — use --build-arg OTEL_ENABLED=false to omit them.

Project structure

DirectoryPurpose
src/index.tscreateApp() entry point — registers tools and inits services.
src/configServer-specific environment variable parsing and validation with Zod.
src/mcp-server/toolsTool definitions (*.tool.ts) — osv_query_package, osv_query_batch, osv_query_commit, osv_get_vulnerability, osv_list_ecosystems.
src/services/osv-apiOSV.dev REST API service — fetch, retry, response normalization.
tests/Unit and integration tests mirroring src/.
skills/Published dependency-audit and advisory-retrieval guide, also served over MCP.

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:

sh
bun run devcheckbun run test

License

Apache-2.0 — see LICENSE for details.

來源:README.md,提交 beaf294

工具

5

osv_list_ecosystems

Osv List Ecosystems

Return the supported ecosystem base names for osv_query_package and osv_query_batch: every ecosystem the OSV schema names that OSV.dev accepts at query time, plus GIT, as verified on 2026-10-31. Known base names are case-insensitive. Preserve suffix spelling. Alpine needs a release branch, such as Alpine:v3.17. The list is static and may lag ecosystems added after that date.

無需輸入參數。

osv_query_package

Osv Query Package

Query known vulnerabilities for a single package version using {name, ecosystem, version} or {purl, version?}; supply exactly one embedded or separate version. Release-qualified Ubuntu names are resolved to the source packages OSV indexes. Returns all matching OSV advisories with severity (CVSS vectors), CVE aliases, affected version ranges, and the fixed versions listed for the queried package. Find canonical ecosystem names and the Alpine release format in osv_list_ecosystems. Known base names are case-insensitive. Preserve suffix spelling. For overflow, repeat the original input with page: overflow.page. Continue the same path with offset: page.nextOffset and revision: page.revision until nextOffset is null. Retrieve each entries[].deferred.path separately at offset zero without a revision. Do not pass the output page object as input. Set page.advisoryId to an announced ID to fetch its fields with fixes and severity for the queried package; retain advisoryId on subsequent pages. Pages are fresh lookups; restart a changed node without a revision. Transmission overflow and upstream truncated are separate; neither confirms clean.

輸入參數namepagepurlcursorversionecosystem

osv_get_vulnerability

Osv Get Vulnerability

Fetch the full advisory record for an OSV vulnerability ID. Returns the complete record: summary, full details text, CVE aliases, all affected packages and version ranges, fix versions, CVSS severity vectors, CWE weakness IDs, and references. Use when osv_query_package or osv_query_batch returns a vuln ID and you need the full advisory context — affected packages or remediation guidance. For overflow, repeat the original input with page: overflow.page. Continue the same path with offset: page.nextOffset and revision: page.revision until nextOffset is null. Retrieve each entries[].deferred.path separately at offset zero without a revision. Do not pass the output page object as input. Every page is a fresh lookup; restart a changed node without a revision. Transmission overflow and upstream truncation are separate; neither confirms clean.

輸入參數id必填page

osv_query_batch

Osv Query Batch

Query vulnerabilities for multiple packages in one call — the primary tool for dependency audits, SBOM scanning, and lockfile triage. Submit up to 5000 mixed {name, ecosystem, version} tuples and {purl, version?} identifiers, with exactly one embedded or separate version per PURL. The first 1000 entries are processed. Follow summary.nextInputOffset to submit the remaining slice. Pass a row's nextCursor as cursor to osv_query_package with that row's identifier. Each entry in the response corresponds positionally to the input. Each finding includes CVE aliases for chaining to nist-nvd-mcp-server for CVSS scoring. Large replies retain the complete summary. For overflow, repeat the original packages array with page: overflow.page. Continue the same path with offset: page.nextOffset and revision: page.revision until nextOffset is null. Retrieve each entries[].deferred.path separately at offset zero without a revision. Do not pass the output page object as input. /results/17 selects original input row 17, even when earlier rows failed. Pages are fresh lookups and do not recompute the initial summary; restart a changed node without a revision. Transmission overflow and upstream truncated are separate; neither confirms clean.

輸入參數pagepackages必填

osv_query_commit

Osv Query Commit

Query known vulnerabilities for one full Git commit hash (40 hexadecimal SHA-1 or 64 hexadecimal SHA-256 characters, case-insensitive). Abbreviated hashes are rejected. Returns advisory summaries, record-wide severity and GIT ranges with repositories and ordered fix events; use osv_get_vulnerability for full records. No package-specific fixedVersions are inferred. For overflow, repeat the original input with page: overflow.page. Continue the same path with offset: page.nextOffset and revision: page.revision until nextOffset is null. Retrieve entries[].deferred.path separately at offset zero without a revision. Do not pass the output page object as input. Pages are fresh lookups; restart a changed node without a revision. Transmission overflow and upstream truncated are separate; neither confirms clean.

輸入參數pagecommit必填cursor

版本歷史

11
  1. v0.6.0最新Nov 21, 2026
  2. v0.5.1Nov 14, 2026
  3. v0.5.0Nov 11, 2026
  4. v0.4.1Nov 1, 2026
  5. v0.4.0Oct 30, 2026
  6. v0.3.0Oct 18, 2026
  7. v0.2.0Oct 14, 2026
  8. v0.1.16Oct 9, 2026
  9. v0.1.15Sep 24, 2026
  10. v0.1.14Sep 20, 2026
  11. v0.1.13Sep 16, 2026

評分

已滿足適用檢查項的 100%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分
  • 已宣告認證方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分