OSV MCP Server

1# OSV MCP Server
2[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/StacklokLabs/osv-mcp)](https://archestra.ai/mcp-catalog/stackloklabs__osv-mcp)
3 
4An MCP (Model Context Protocol) server that provides access to the
5[OSV (Open Source Vulnerabilities) database](https://osv.dev/).
6 
7## Overview
8 
9This project implements an SSE-based MCP server that allows LLM-powered
10applications to query the OSV database for vulnerability information. The server
11provides tools for:
12 
131. Querying vulnerabilities for a specific package version or commit
142. Batch querying vulnerabilities for multiple packages or commits
153. Getting detailed information about a specific vulnerability by ID
16 
17## Installation
18 
19### Prerequisites
20 
21- Go 1.21 or later
22- [Task](https://taskfile.dev/) (optional, for running tasks)
23- [ko](https://ko.build/) (optional, for building container images)
24 
25### Building from source
26 
27```bash
28# Clone the repository
29git clone https://github.com/StacklokLabs/osv-mcp.git
30cd osv-mcp
31 
32# Build the server
33task build
34```
35 
36## Usage
37 
38### Running with ToolHive (Recommended)
39 
40The easiest way to run the OSV MCP server is using
41[ToolHive](https://github.com/stacklok/toolhive), which provides secure,
42containerized deployment of MCP servers:
43 
44```bash
45# Install ToolHive (if not already installed)
46# See: https://docs.stacklok.com/toolhive/guides-cli/install
47 
48# Register a supported client so ToolHive can auto-configure your environment
49thv client setup
50 
51# Run the OSV MCP server (packaged as 'osv' in ToolHive)
52thv run osv
53 
54# List running servers
55thv list
56 
57# Get detailed information about the server
58thv registry info osv
59```
60 
61The server will be available to your MCP-compatible clients and can query the
62OSV database for vulnerability information.
63 
64### Running from Source
65 
66### Server Configuration
67 
68The server can be configured using environment variables:
69 
70- `MCP_PORT`: The port number to run the server on (default: 8080)
71 
72  - Must be a valid integer between 0 and 65535
73  - If invalid or not set, the server will use port 8080
74 
75- `MCP_TRANSPORT`: The transport mode for the server (default: `sse`)
76  - Supported values: `sse`, `streamable-http`
77  - If invalid or not set, the server will use SSE transport mode
78 
79Example:
80 
81```bash
82# Run on port 3000
83MCP_PORT=3000 ./build/osv-mcp-server
84 
85# Run on default port 8080
86./build/osv-mcp-server
87```
88 
89### MCP Tools
90 
91The server provides the following MCP tools:
92 
93#### query_vulnerability
94 
95Query for vulnerabilities affecting a specific package version or commit.
96 
97**Input Schema:**
98 
99```json
100{
101  "type": "object",
102  "properties": {
103    "commit": {
104      "type": "string",
105      "description": "The commit hash to query for. If specified, version should not be set."
106    },
107    "version": {
108      "type": "string",
109      "description": "The version string to query for. If specified, commit should not be set."
110    },
111    "package_name": {
112      "type": "string",
113      "description": "The name of the package."
114    },
115    "ecosystem": {
116      "type": "string",
117      "description": "The ecosystem for this package (e.g., PyPI, npm, Go)."
118    },
119    "purl": {
120      "type": "string",
121      "description": "The package URL for this package. If purl is used, package_name and ecosystem should not be set."
122    }
123  }
124}
125```
126 
127#### query_vulnerabilities_batch
128 
129Query for vulnerabilities affecting multiple packages or commits at once.
130 
131**Input Schema:**
132 
133```json
134{
135  "type": "object",
136  "properties": {
137    "queries": {
138      "type": "array",
139      "description": "Array of query objects",
140      "items": {
141        "type": "object",
142        "properties": {
143          "commit": {
144            "type": "string",
145            "description": "The commit hash to query for. If specified, version should not be set."
146          },
147          "version": {
148            "type": "string",
149            "description": "The version string to query for. If specified, commit should not be set."
150          },
151          "package_name": {
152            "type": "string",
153            "description": "The name of the package."
154          },
155          "ecosystem": {
156            "type": "string",
157            "description": "The ecosystem for this package (e.g., PyPI, npm, Go)."
158          },
159          "purl": {
160            "type": "string",
161            "description": "The package URL for this package. If purl is used, package_name and ecosystem should not be set."
162          }
163        }
164      }
165    }
166  },
167  "required": ["queries"]
168}
169```
170 
171#### get_vulnerability
172 
173Get details for a specific vulnerability by ID.
174 
175**Input Schema:**
176 
177```json
178{
179  "type": "object",
180  "properties": {
181    "id": {
182      "type": "string",
183      "description": "The OSV vulnerability ID"
184    }
185  },
186  "required": ["id"]
187}
188```
189 
190## Examples
191 
192### Querying vulnerabilities for a package
193 
194```json
195{
196  "package_name": "lodash",
197  "ecosystem": "npm",
198  "version": "4.17.15"
199}
200```
201 
202### Querying vulnerabilities for a commit
203 
204```json
205{
206  "commit": "6879efc2c1596d11a6a6ad296f80063b558d5e0f"
207}
208```
209 
210### Batch querying vulnerabilities
211 
212```json
213{
214  "queries": [
215    {
216      "package_name": "lodash",
217      "ecosystem": "npm",
218      "version": "4.17.15"
219    },
220    {
221      "package_name": "jinja2",
222      "ecosystem": "PyPI",
223      "version": "2.4.1"
224    }
225  ]
226}
227```
228 
229### Getting vulnerability details
230 
231```json
232{
233  "id": "GHSA-vqj2-4v8m-8vrq"
234}
235```
236 
237## Development
238 
239### Running tests
240 
241```bash
242task test
243```
244 
245### Linting
246 
247```bash
248task lint
249```
250 
251### Formatting code
252 
253```bash
254task fmt
255```
256 
257## Contributing
258 
259We welcome contributions to this MCP server! If you'd like to contribute, please
260review the [CONTRIBUTING guide](./CONTRIBUTING.md) for details on how to get
261started.
262 
263If you run into a bug or have a feature request, please
264[open an issue](https://github.com/StacklokLabs/osv-mcp/issues) in the
265repository or join us in the `#mcp-servers` channel on our
266[community Discord server](https://discord.gg/stacklok).
267 
268## License
269 
270This project is licensed under the Apache v2 License - see the LICENSE file for
271details.
272