OSV Vulnerability Database MCP server for AI agents

The OSV MCP Server provides access to the Open Source Vulnerabilities (OSV) database through a Model Context Protocol implementation. It enables LLM-powered applications to query vulnerability information for packages and commits using a standardized interface.

Installation

Prerequisites

Go 1.21 or later
Task (optional, for running tasks)
ko (optional, for building container images)

Building from Source

# Clone the repository
git clone https://github.com/StacklokLabs/osv-mcp.git
cd osv-mcp

# Build the server
task build

Usage

Running with ToolHive

The easiest way to run the OSV MCP server is using ToolHive, which provides secure, containerized deployment of MCP servers:

# Install ToolHive (if not already installed)
# See: https://docs.stacklok.com/toolhive/guides-cli/install

# Register a supported client so ToolHive can auto-configure your environment
thv client setup

# Run the OSV MCP server (packaged as 'osv' in ToolHive)
thv run osv

# List running servers
thv list

# Get detailed information about the server
thv registry info osv

Server Configuration

The server can be configured using environment variables:

MCP_PORT: The port number to run the server on (default: 8080)
- Must be a valid integer between 0 and 65535
- If invalid or not set, the server will use port 8080
MCP_TRANSPORT: The transport mode for the server (default: sse)
- Supported values: sse, streamable-http
- If invalid or not set, the server will use SSE transport mode

Example:

# Run on port 3000
MCP_PORT=3000 ./build/osv-mcp-server

# Run on default port 8080
./build/osv-mcp-server

Available MCP Tools

query_vulnerability

Query for vulnerabilities affecting a specific package version or commit.

Input Schema:

{
  "type": "object",
  "properties": {
    "commit": {
      "type": "string",
      "description": "The commit hash to query for. If specified, version should not be set."
    },
    "version": {
      "type": "string",
      "description": "The version string to query for. If specified, commit should not be set."
    },
    "package_name": {
      "type": "string",
      "description": "The name of the package."
    },
    "ecosystem": {
      "type": "string",
      "description": "The ecosystem for this package (e.g., PyPI, npm, Go)."
    },
    "purl": {
      "type": "string",
      "description": "The package URL for this package. If purl is used, package_name and ecosystem should not be set."
    }
  }
}

query_vulnerabilities_batch

Query for vulnerabilities affecting multiple packages or commits at once.

Input Schema:

{
  "type": "object",
  "properties": {
    "queries": {
      "type": "array",
      "description": "Array of query objects",
      "items": {
        "type": "object",
        "properties": {
          "commit": {
            "type": "string",
            "description": "The commit hash to query for. If specified, version should not be set."
          },
          "version": {
            "type": "string",
            "description": "The version string to query for. If specified, commit should not be set."
          },
          "package_name": {
            "type": "string",
            "description": "The name of the package."
          },
          "ecosystem": {
            "type": "string",
            "description": "The ecosystem for this package (e.g., PyPI, npm, Go)."
          },
          "purl": {
            "type": "string",
            "description": "The package URL for this package. If purl is used, package_name and ecosystem should not be set."
          }
        }
      }
    }
  },
  "required": ["queries"]
}

get_vulnerability

Get details for a specific vulnerability by ID.

Input Schema:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The OSV vulnerability ID"
    }
  },
  "required": ["id"]
}

Usage Examples

Querying vulnerabilities for a package

{
  "package_name": "lodash",
  "ecosystem": "npm",
  "version": "4.17.15"
}

Querying vulnerabilities for a commit

{
  "commit": "6879efc2c1596d11a6a6ad296f80063b558d5e0f"
}

Batch querying vulnerabilities

{
  "queries": [
    {
      "package_name": "lodash",
      "ecosystem": "npm",
      "version": "4.17.15"
    },
    {
      "package_name": "jinja2",
      "ecosystem": "PyPI",
      "version": "2.4.1"
    }
  ]
}

Getting vulnerability details

{
  "id": "GHSA-vqj2-4v8m-8vrq"
}

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "osv" '{"command":"thv","args":["run","osv"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "osv": {
            "command": "thv",
            "args": [
                "run",
                "osv"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "osv": {
            "command": "thv",
            "args": [
                "run",
                "osv"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect