Kodus OSV

Open source vulnerability lookup via osv_query/osv_query_batch tools.

GitHub

OSV MCP Server (Bun)

Remote Model Context Protocol (MCP) HTTP server that wraps the OSV v1 API for on-demand open-source vulnerability lookups (example feed: https://osv.dev/list?q=%40NESTJS%2FCORE&ecosystem=npm). Exported as MCP tools so agents can query OSV directly.

Features

  • Streamable HTTP MCP endpoint at /mcp.
  • Tools: osv_query (single target) and osv_query_batch (multiple).
  • Configurable base URL (OSV_API_URL, defaults to https://api.osv.dev/v1).
  • Clear schemas and validation to guide LLMs (commit XOR version, purl rules, pagination).

Quick start

Requirements: Bun.

bun install
PORT=3000 HOST=0.0.0.0 OSV_API_URL=https://api.osv.dev/v1 bun run index.ts

MCP endpoint: http://<host>:<port>/mcp.

Env vars:

  • PORT / HOST: HTTP bind (default 3000 / 0.0.0.0).
  • OSV_API_URL: override OSV base URL.

MCP client setup

  • Claude Code CLI: claude mcp add --transport http mcp-osv http://localhost:3000/mcp
  • VS Code: code --add-mcp "{\"name\":\"mcp-osv\",\"type\":\"http\",\"url\":\"http://localhost:3000/mcp\"}"
  • MCP Inspector: npx @modelcontextprotocol/inspector -> connect to http://localhost:3000/mcp Replace localhost with your host/port if remote.

Tools and parameters

osv_query

{
  "commit": "sha OR",
  "version": "version string OR",
  "package": {
    "name": "required with ecosystem if not using purl",
    "ecosystem": "required with name if not using purl",
    "purl": "pkg:pypi/jinja2 // purl OR name+ecosystem; if version is present, omit @version here"
  },
  "pageToken": "optional pagination token from previous OSV response"
}

Rules:

  • Use commit XOR version (one or the other, never both).
  • If version is present, package is required.
  • package must be either purl or (name + ecosystem).
  • If version exists and package.purl is used, omit @version in the purl.

osv_query_batch

{
  "queries": [
    {
      "commit": "sha OR",
      "version": "version string OR",
      "package": {
        "name": "pkg name",
        "ecosystem": "ecosystem",
        "purl": "pkg:ecosys/name"
      },
      "pageToken": "optional"
    }
  ]
}

Rules: each item follows the same rules as osv_query.

Example calls

  • PyPI version: {"package":{"purl":"pkg:pypi/jinja2"},"version":"3.1.4"}
  • npm with name+ecosystem: {"package":{"name":"@nestjs/core","ecosystem":"npm"},"version":"10.2.10"}
  • Commit lookup: {"commit":"<sha>","package":{"ecosystem":"Go","name":"github.com/foo/bar"}}

Debugging

  • Server log: OSV MCP server listening on http://<host>:<port>/mcp
  • Curl init: curl -H "content-type: application/json" -H "accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"curl","version":"0.0.0"},"capabilities":{}}}' http://localhost:3000/mcp
  • List tools: same endpoint with {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

License

MIT License. See LICENSE.

Related Servers