[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_115":116},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module '@cyanheads/osv-advisory-mcp-server' is not configured","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":26,"_34":-5,"_35":36,"_37":-5,"_38":-5,"_39":40,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":48,"_56":57,"_58":59,"_60":-5,"_61":-5,"_62":-5,"_63":-5,"_64":65,"_66":67,"_68":69,"_70":71,"_72":73,"_74":-5,"_75":-5,"_76":-5,"_77":48,"_78":-5,"_79":80,"_81":82,"_83":84,"_85":86,"_87":88,"_89":90,"_91":92},"apiUrl","https://odel.app/api","creator","cyanheads","moduleId","osv-advisory-mcp-server","@cyanheads/osv-advisory-mcp-server","displayName","osv advisory mcp server","tagline","Query OSV.dev for package vulnerabilities and batch-audit dependency lists via MCP.","iconKey","https://avatars.githubusercontent.com/u/10339515?v=4","category","dev-tools","status","published","metaDescription","metaKeywords","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://osv-advisory.caseyjhand.com/mcp\",\"transport\":\"streamable-http\",\"authType\":\"none\"}","pricingModel","free","creatorUserId","system:external-import","createdAt",1781363414000,"updatedAt",1781499625000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.cyanheads%2Fosv-advisory-mcp-server","sourceVerified",true,"importedAt","upstreamStars",1,"upstreamUpdatedAt",1781321681000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/cyanheads/osv-advisory-mcp-server","githubRepoFullName","cyanheads/osv-advisory-mcp-server","releaseId","ext-cyanheads-osv-advisory-mcp-server","version","0.1.5","descriptionMarkdown","

@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.\n

4 Tools

\n\n

\n\n[![Version](https://img.shields.io/badge/Version-0.1.5-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/osv-advisory-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/osv-advisory-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/osv-advisory-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun->=1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)\n\n

\n\n

\n\n[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/osv-advisory-mcp-server/releases/latest/download/osv-advisory-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=osv-advisory-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvb3N2LWFkdmlzb3J5LW1jcC1zZXJ2ZXIiXX0=) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22osv-advisory-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fosv-advisory-mcp-server%22%5D%7D)\n\n[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n

\n\n

\n\n**Public Hosted Server:** [https://osv-advisory.caseyjhand.com/mcp](https://osv-advisory.caseyjhand.com/mcp)\n\n

\n\n---\n\n## Tools\n\n4 tools for querying the OSV.dev vulnerability database — single package lookups, batch dependency audits, and full advisory fetch:\n\n| Tool | Description |\n|:---|:---|\n| `osv_query_package` | Query known vulnerabilities for a single package version by name, ecosystem, and version |\n| `osv_query_batch` | Batch vulnerability query for an array of package tuples — one call for a full dependency list or SBOM audit |\n| `osv_get_vulnerability` | Fetch the full advisory record for a single OSV vulnerability ID |\n| `osv_list_ecosystems` | Return the list of supported ecosystem identifier strings |\n\n### `osv_query_package`\n\nThe primary \"is this package version vulnerable?\" tool.\n\n- Accepts `name`, `ecosystem` (case-sensitive exact match — use `osv_list_ecosystems` to validate), and `version`\n- Returns all matching advisories: OSV IDs, CVE aliases, CVSS severity vectors, derived severity label, first safe versions, affected version ranges (SEMVER/ECOSYSTEM/GIT), and CWE IDs\n- `aliases` field surfaces CVE IDs for chaining to `nist-nvd-mcp-server` for CVSS base scores, EPSS exploitation probability, and CISA KEV status\n- No API key required — OSV.dev is fully public and keyless\n\n---\n\n### `osv_query_batch`\n\nThe primary tool for dependency audits, SBOM scanning, and lockfile triage.\n\n- Accepts an array of `{name, ecosystem, version}` tuples (1–1000 packages per call)\n- All ecosystems are pre-validated before the API call — a single invalid ecosystem string fails the batch (OSV API behavior)\n- Returns per-package results positionally matching the input, with `vulnerable`, `vulnCount`, `vulns` (including `aliases` and `severityLabel`), and `fixedVersions`\n- Includes aggregate summary: `totalPackages`, `vulnerableCount`, `cleanCount`, `errorCount`, `totalVulns`, `worstSeverity`\n\n---\n\n### `osv_get_vulnerability`\n\nFetch the complete advisory record by OSV ID.\n\n- Accepts any OSV ID prefix: `GHSA-` (GitHub), `PYSEC-` (Python), `RUSTSEC-` (Rust), `GO-` (Go), `DSA-`/`DLA-` (Debian), `CVE-` (direct CVE fallbacks)\n- Returns: summary, full advisory details text, all CVE aliases, all affected packages and their version ranges, fix versions, CVSS severity vectors, CWE weakness IDs, and references (ADVISORY, FIX, REPORT, etc.)\n- Use after `osv_query_package` or `osv_query_batch` returns a vuln ID and you need the full advisory context — remediation guidance, scope of affected packages, or eligibility criteria\n\n---\n\n### `osv_list_ecosystems`\n\nReturn the list of valid ecosystem identifier strings. Ecosystem strings are **case-sensitive exact matches** — `\"pypi\"` is not `\"PyPI\"`. Call this tool before querying to validate ecosystem strings from lockfiles or user input. The list is static (sourced from the OSV schema spec) and may occasionally lag newly added ecosystems.\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool definitions — single file per tool, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports\n\nOSV-specific:\n\n- No API key required — OSV.dev is fully public, keyless, and has no published rate limit\n- Parallel single-package queries in `osv_query_batch` return full records including `aliases` (CVE IDs) that the upstream batch endpoint omits\n- Ecosystem pre-validation guards against OSV's all-or-nothing batch rejection behavior\n\nAgent-friendly output:\n\n- `aliases` (CVE IDs) prominently surfaced on every vuln entry — the primary composition point for chaining to `nist-nvd-mcp-server` for CVSS base scores, EPSS, and CISA KEV status\n- `severityLabel` derived from `database_specific.severity` (GHSA records) or the highest CVSS base score; `null` rather than fabricated when neither source is available\n- Echo of query parameters (`queryMeta`) on `osv_query_package` output so agents can verify the request was applied correctly\n- Batch aggregate summary (`worstSeverity`, `vulnerableCount`, `cleanCount`) for quick triage without reading per-package rows\n\n## Getting started\n\n### Public Hosted Instance\n\nA public instance is available at `https://osv-advisory.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:\n\n```json\n{\n \"mcpServers\": {\n \"osv-advisory-mcp-server\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://osv-advisory.caseyjhand.com/mcp\"\n }\n }\n}\n```\n\n### Self-Hosted / Local\n\nAdd the following to your MCP client configuration file. No API key is required — OSV.dev is fully public.\n\n```json\n{\n \"mcpServers\": {\n \"osv-advisory-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/osv-advisory-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"osv-advisory-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/osv-advisory-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"osv-advisory-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"ghcr.io/cyanheads/osv-advisory-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).\n- No API key required — OSV.dev is fully public.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/osv-advisory-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd osv-advisory-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment:**\n\n```sh\ncp .env.example .env\n# edit .env if needed (no required vars)\n```\n\n## Configuration\n\nAll configuration is validated at startup. No server-specific env vars are required — OSV.dev is keyless and fully public.\n\n| Variable | Description | Default |\n|:---------|:------------|:--------|\n| `OSV_REQUEST_TIMEOUT_MS` | HTTP request timeout in milliseconds for OSV.dev API calls. | `10000` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |\n| `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path. | `/mcp` |\n| `MCP_PUBLIC_URL` | Public origin override for TLS-terminating reverse-proxy deployments. | none |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |\n| `LOGS_DIR` | Directory for log files (Node.js only). | `/logs` |\n| `STORAGE_PROVIDER_TYPE` | Storage backend. | `in-memory` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) (spans, metrics, completion logs). | `false` |\n\nSee [`.env.example`](https://github.com/cyanheads/osv-advisory-mcp-server/blob/main/.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t osv-advisory-mcp-server .\ndocker run --rm -p 3010:3010 osv-advisory-mcp-server\n```\n\nThe 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.\n\n## Project structure\n\n| Directory | Purpose |\n|:----------|:--------|\n| `src/index.ts` | `createApp()` entry point — registers tools and inits services. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`) — `osv_query_package`, `osv_query_batch`, `osv_get_vulnerability`, `osv_list_ecosystems`. |\n| `src/services/osv-api` | OSV.dev REST API service — fetch, retry, response normalization. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`CLAUDE.md`/`AGENTS.md`](https://github.com/cyanheads/osv-advisory-mcp-server/blob/main/CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Register new tools via the barrel in `src/mcp-server/tools/definitions/index.ts`\n- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](https://github.com/cyanheads/osv-advisory-mcp-server/blob/main/LICENSE) for details.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"categoryDisplayName","Developer Tools","upstream",{"_95":96,"_97":98,"_99":100,"_101":102,"_103":-5},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_93":80,"_94":80},"ratingAvg","reviewCount","topics",[104,105,19,106,107,108,109,110,111,112,113,114],"license","Apache-2.0","language","TypeScript","registryName","io.github.cyanheads/osv-advisory-mcp-server","homepage","ai-agents","ai-tools","devsecops","mcp","mcp-server","model-context-protocol","osv","sbom","security","typescript","vulnerability","ENV",{"_117":118,"_119":120,"_121":122},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]