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 分