# MCP Server Integration in OSV-Scanner: Complete Guide to LLM-Based Vulnerability Scanning

> Master MCP server integration in OSV-Scanner for LLM-based vulnerability scanning. Access dependency scans and advisory details via JSON-RPC. Explore the complete guide.

- Repository: [Google/osv-scanner](https://github.com/google/osv-scanner)
- Tags: deep-dive
- Published: 2026-04-25

---

**The OSV-Scanner MCP server integration exposes vulnerability scanning capabilities via the Model Context Protocol, enabling LLM-driven tools to execute dependency scans and retrieve advisory details through JSON-RPC over STDIO or SSE.**

The `google/osv-scanner` repository includes an experimental MCP (Model Context Protocol) server that transforms the command-line scanner into an LLM-accessible service. This integration allows AI assistants and automated tools to programmatically detect vulnerabilities without wrapping the traditional CLI, supporting both local STDIO and networked SSE transport modes.

## What is the MCP Server Integration?

The MCP server integration, found under `cmd/osv-scanner/mcp/`, implements the Model Context Protocol—a lightweight JSON-RPC specification designed for LLM tool integration. According to the source code in [`command.go`](https://github.com/google/osv-scanner/blob/main/command.go), the server registers as the `experimental-mcp` subcommand and exposes three primary tools that wrap OSV-Scanner's core functionality. Unlike the standard CLI interface, this integration enables bidirectional communication with AI systems, allowing them to trigger scans, cache results, and retrieve detailed vulnerability metadata on demand.

## Available MCP Tools and Capabilities

The server implements three distinct MCP tools registered via `mcp.AddTool` in [`cmd/osv-scanner/mcp/command.go`](https://github.com/google/osv-scanner/blob/main/cmd/osv-scanner/mcp/command.go):

### scan_vulnerable_dependencies

This tool executes a standard OSV-Scanner analysis against specified directories. The `handleScan` function wraps `osvscanner.DoScan`, caches discovered vulnerabilities in a thread-safe map, and returns formatted text output suitable for LLM consumption. It accepts parameters for recursive scanning, path globbing, and ignore patterns.

### get_vulnerability_details

Given an OSV vulnerability ID (e.g., `GO-2023-1558`), the `handleVulnIDRetrieval` function returns the full JSON representation of the advisory. The implementation checks a global vulnerability cache (protected by `vulnCacheMu`) before querying the OSV-dev API, then marshals the protobuf data into pretty-printed JSON for client consumption.

### ignore_vulnerability

The `handleIgnoreVulnerability` function returns embedded markdown documentation ([`configuration-instructions.md`](https://github.com/google/osv-scanner/blob/main/configuration-instructions.md)) that instructs LLMs on how to generate proper ignore-files for OSV-Scanner. This enables automated remediation workflows where AI agents can suppress false positives programmatically.

## Architecture and Source Implementation

The MCP implementation resides in [`cmd/osv-scanner/mcp/command.go`](https://github.com/google/osv-scanner/blob/main/cmd/osv-scanner/mcp/command.go) and follows a structured server pattern:

1. **Server Initialization**: Creates `mcp.NewServer` with the OSV-Scanner name and version
2. **Tool Registration**: Binds handler functions to MCP tool names using `mcp.AddTool`
3. **Prompt Registration**: Exposes a predefined `scan_deps` prompt to provide LLM context
4. **Transport Selection**: Switches between `mcp.StdioTransport` (default) and SSE mode via the `--sse` flag

The vulnerability cache mechanism uses a global `map[string]*osvschema.Vulnerability` protected by an `RWMutex` (`vulnCacheMu`), ensuring that repeated calls to `get_vulnerability_details` for the same vulnerability ID do not trigger redundant API requests.

## How to Run the MCP Server

### STDIO Mode (Default)

STDIO mode communicates over the process' standard input and output, ideal for local LLM integrations:

```bash
osv-scanner experimental-mcp

```

The process reads MCP JSON-RPC requests from `stdin` and writes responses to `stdout`.

### SSE Mode (Networked)

SSE mode enables remote access by creating an HTTP server with `mcp.NewSSEHandler`:

```bash
osv-scanner experimental-mcp --sse localhost:8080

```

This listens on `http://localhost:8080/sse` for MCP clients, allowing centralized scanner instances to serve multiple remote LLM backends.

## Client Integration Examples

The integration test in [`cmd/osv-scanner/mcp/integration_test.go`](https://github.com/google/osv-scanner/blob/main/cmd/osv-scanner/mcp/integration_test.go) demonstrates the exact client implementation. Below is a practical Go example connecting via SSE:

```go
package main

import (
	"context"
	"log"

	"github.com/modelcontextprotocol/go-sdk/mcp"
)

func main() {
	// Connect to MCP server via SSE
	transport := &mcp.SSEClientTransport{
		Endpoint: "http://localhost:8080/sse",
	}
	client := mcp.NewClient(&mcp.Implementation{
		Name:    "my-client",
		Version: "1.0.0",
	}, nil)

	sess, err := client.Connect(context.Background(), transport, nil)
	if err != nil {
		log.Fatalf("connect error: %v", err)
	}
	defer sess.Close()

	// Scan vulnerable dependencies
	scanRes, err := sess.CallTool(context.Background(), &mcp.CallToolParams{
		Name: "scan_vulnerable_dependencies",
		Arguments: map[string]any{
			"paths":                []string{"./my-project"},
			"recursive":            true,
			"ignore_glob_patterns": []string{},
		},
	})
	if err != nil {
		log.Fatalf("scan error: %v", err)
	}
	log.Printf("Scan output:\n%s", scanRes.Content[0].(*mcp.TextContent).Text)

	// Retrieve specific vulnerability details
	detailRes, err := sess.CallTool(context.Background(), &mcp.CallToolParams{
		Name: "get_vulnerability_details",
		Arguments: map[string]any{
			"vuln_id": "GO-2023-1558",
		},
	})
	if err != nil {
		log.Fatalf("details error: %v", err)
	}
	log.Printf("Vuln JSON:\n%s", detailRes.Content[0].(*mcp.TextContent).Text)
}

```

The client sends JSON payloads matching the input structs defined in [`command.go`](https://github.com/google/osv-scanner/blob/main/command.go) (`scanVulnerableDependenciesInput` and `getVulnerabilityDetailsInput`), receiving responses wrapped in `mcp.TextContent` containers.

## Summary

- The **OSV-Scanner MCP integration** provides LLM-accessible vulnerability scanning via the `experimental-mcp` subcommand in [`cmd/osv-scanner/mcp/command.go`](https://github.com/google/osv-scanner/blob/main/cmd/osv-scanner/mcp/command.go).
- **Three tools** expose core functionality: `scan_vulnerable_dependencies`, `get_vulnerability_details`, and `ignore_vulnerability`.
- **Dual transport support** includes STDIO for local integration and SSE (`--sse` flag) for networked deployments.
- **Built-in caching** via `vulnCacheMu` prevents redundant API calls when retrieving vulnerability details.
- **Integration tests** in [`integration_test.go`](https://github.com/google/osv-scanner/blob/main/integration_test.go) provide working examples of client-server communication.

## Frequently Asked Questions

### What is the Model Context Protocol (MCP)?

The Model Context Protocol is a lightweight JSON-RPC specification that standardizes how LLM-driven tools communicate with external services. In OSV-Scanner, it enables AI assistants to execute scans and retrieve vulnerability data through structured requests rather than parsing command-line output.

### Is the MCP server in OSV-Scanner production-ready?

No, the MCP server is explicitly marked as **experimental** in the source code and documentation. The implementation in [`cmd/osv-scanner/mcp/command.go`](https://github.com/google/osv-scanner/blob/main/cmd/osv-scanner/mcp/command.go) and the associated [`docs/experimental.md`](https://github.com/google/osv-scanner/blob/main/docs/experimental.md) file indicate that APIs and transport mechanisms may change in future releases.

### How does vulnerability caching work in the MCP implementation?

The server maintains a global `map[string]*osvschema.Vulnerability` protected by an `RWMutex` named `vulnCacheMu`. When `scan_vulnerable_dependencies` runs, discovered vulnerabilities populate this cache, allowing `get_vulnerability_details` to serve subsequent requests for the same OSV ID without querying the remote OSV-dev API.

### Can I integrate this with Claude, Gemini, or other LLM assistants?

Yes, any MCP-compatible client can connect to the OSV-Scanner server. For STDIO mode, configure your LLM tool to spawn `osv-scanner experimental-mcp` as a subprocess. For SSE mode, point the client to the HTTP endpoint specified with the `--sse` flag (e.g., `http://localhost:8080/sse`). The protocol is transport-agnostic and works with any MCP-compliant implementation.